i * 

K r .* MLoATtwCh 
WOta 1 90940 



^L. 



A Further Development of The 
Massachusetts Institute of Technology 
Computer Aided Design Executive System 

by 

LIEUTENANT COMMANDER DAVID LEE STONE, U.S. NAVY 

B.S.E.E., Purdue University 
(1973) 

SUBMITTED TO THE DEPARTMENTS OF 
OCEAN ENGINEERING AND MECHANICAL ENGINEERING 
IN PARTIAL FULFILLMENT OF THE REQUIREMENTS 
FOR THE DEGREES OF 

OCEAN ENGINEER 
and 

MASTER OF SCIENCE IN MECHANICAL ENGINEERING 

at the 

MASSACHUSETTS INSTITUTE OF TECHNOLOGY 
June 1982 

©David Lee Stone 1982 

The author hereby grants to M.I.T. permission to reproduce 
and to distribute copies of this thesis document in whole or 



DUDLEY KNO^: LIDRARY 
NAVAL POSTGRADUATE SCHOOL 
MONTEREY, CALIF. 93940 



A FURTHER DEVELOPMENT OF THE 
MASSACHUSETTS INSTITUTE OF TECHNOLOGY 
COMPUTER AIDED DESIGN EXECUTIVE SYSTEM 

by 

DAVID LEE STONE 

Submitted to the Department of Ocean Engineering 
on May 07, 1982 in partial fulfillment 
of the requirements for the Degrees of 
Ocean Engineer 
and 

Master of Science in Mechanical Engineering 



ABSTRACT 



The MIT Design 
DEX, is a design 
system. DEX provi 
trolled environmen 
program modules, 
structured design e 
menus . 



Executive System, which is referred to as 
oriented, structured interactive computer 
des the designer with a flexible but con- 
t in which to interact through DEX with 
databases, and the operating system. The 
nvironment is provided through the use of 



A further development of the MIT Computer Aided Design 
Executive system provides truly dynamic loading of program 
modules at execution time. A dynamic storage capability is 
added along with the capability to determine file status and 
dynamically allocate files during execution of DEX. In the 
event of an abnormal termination of execution, this condi- 
tion is trapped and any open database is saved. 

Improvements are added to the present DEX database 
system, with compression of the database after delete. 
Backward pointers are added, and a proposal for a dynam- 
ically extendible database is provided. 
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CHAPTER 1 



BACKGROUND AND THESIS ORGANIZATION 



1 . 1 Background 

In recent years the computer has come to the forefront of 
the design process, as numerous computer aided design sys- 
tems have been developed. However, we as designers still do 
not realize the full potential of this powerful tool. There 
are several reasons for this. While the recent improvements 
in the user/ program interface have made the computer more 
straightforward to use, there are still several common prob- 
lems which make the designer unwilling to accept the outlay 
of time required to change from one design program to anoth- 
er. Some of the common problems that these design programs, 
and the systems that contain them suffer from are: 

1. Too often the programs are inflexible, and do not 
allow the user to deviate from the preconceived 
design process. 
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2. There is no consistent input/output procedure, and 
the output of one program cannot easily be used as 
input to another. 

3. Because of the inconsistencies, the user must learn 
new procedures for each new program. This results 
in excessive training time requirements. 

4. The program is often not forgiving, and after 
spending much time running the program an error can 
result in the loss of all output. 

5. Inability of the programs to be transported to oth- 
er facilities. 

6. Often the programs are not user friendly. That is 
they were not designed with the ease of use as a 
major consideration in writing the program. 

In 1974, researchers at the Massachusetts Institute of 
Technology and the University of Michigan joined together in 
a project to develop a structured computer aided design sys- 
tem that would eliminate or reduce the above 
characteristics. They named the system the Design Executive 
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System (DEX) . The DEX system was written in a structured, 
top down manner, with each subroutine having a specific 
function. This was done to enhance transportability. If a 
given function was not available at a facility, then only 
the routine containing that function and the references to 
it would have to be changed. Also when transporting DEX, 
the few site dependent routines would be separate and could 
be easily changed without having to rewrite all of DEX. DEX 
can be adapted to almost any computer system that supports 
the Fortran programming language. 

DEX provides an environment for running various applica- 
tion programs, called "modules". This provides ease of use 
and consistency by requiring all module programmers to 
interface with the user in the same manner. The DEX system 
was designed as a transactional manager that would insulate 
the user from both the module and the operating system, with 
DEX controlling all transactions. DEX consists of three 
levels or groups of programs; 

1. DEX proper - The main body of DEX which provides 
the operating environment or "umbrella" of DEX, 
within which the user and the modules interact. 
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These routines provide the user with the consistent 
impression of the system. 

2. Extended DEX library - These are a collection of 45 
utility subroutines and general functions which can 
be used by the module writer to facilitate the con- 
struction of the module. They are already set up 
to communicate with DEX properly. They include 
routines for reading, writing, editing data, unit 
conversion, and outputing messages and status indi- 
cations . 

3. Module - A module is a single subroutine or a com- 
plete set of subroutines written and executed 
together to perform a specific task. This is the 
actual application program which performs the cal- 
culations that the user is interested in. 

The DEX system will be explained in more detail in Chapter 
2. Celotto in his thesis [Celotto, 1981] gives the refer- 

ences for the earlier work on DEX, and gives an excellent 
example of how to write a module and how to run the DEX sys- 
tem. He also gives a detailed description of the Extended 
DEX library which was primarily his work. 
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1.2 



Purpose 



The purpose of this work is to make a further development 
in DEX proper. The first area of emphasis was in the DEX 
assembly language routines. While DEX is written primarily 
in Fortran for transportability, there are some system func- 
tions that were not available to DEX through Fortran at the 
Massachusetts Institute of Technology. It thus became 
neccessary to write a few functions as site dependent 
IBM/370 assembly language routines. These functional areas 
were : 



• User identification. 

• System time. 

• Enhanced file management routines. 

• Enhanced dynamic loading and unloading of modules. 

• Enhanced dynamic allocation of memory. 

• Enhanced error recovery with recovery from abnormal 
termination . 
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This was my major area of emphasis. 



The second area of emphasis was in the DEX database edit- 
ing routines. To the existing database management system in 
DEX the following capabilities were added: 

• Enhanced delete function. 

• Bi-directional pointers. 

• Compression of the database (elimination of deleted 
entries) when the database is full or at the users 
request . 

• Expansion of the database array buffer when it is 
full through the use of dynamic memory allocation. 

1 . 3 Preview of Things to Come 

Chapter 2 provides further detail on the DEX system. 
Chapter 3 will look at the assembly language utility rou- 
tines, and the DEX philosophy of file management, dynamic 
loading, and dynamic memory allocation. Chapter 4 will give 
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further detail on the DEX database system, what it was, what 
it is now, and how it should be developed in the future. 
Chapter 5 will give conclusions and recommendations for the 
future. Appendix A is an assembly language programmers 
guide, written for the user who desires to write or modify 
DEX assembly language routines. Appendix B is a sample ses- 
sion with DEX's database editor. Appendix C is the program 
listings for the assembly language routines addressed in 
Chapter 3. And finally. Appendix D is the program listings 
for the database routines discussed in Chapter 4. 
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CHAPTER 2 



THE DESIGN EXECUTIVE SYSTEM (DEX) 



2 . 1 The DEX System 



The DEX System is a highly structured interactive Design 
Executive program which manages all interactions between; 
1.) the user, 2.) application program "modules" operating 
within DEX, 3.) DEX databases in memory, 4.) other sources 
and destinations of data, and 5.) the operating system. The 
design philosophy of the DEX System is discussed in the next 
section. DEX provides a major control structure utilizing 
menus to communicate with the user. When in the DEX envi- 
ronment the user is prompted to enter an item from one of 
the DEX menus shown in figure 2.1 indicating the action that 
the user desires to be performed. The menu DEX. MAIN is the 
major DEX control menu, and contains the major DEX commands. 
DEX begins its interaction with the user by prompting for an 
item from this menu, and returns to this menu after the com- 
pletion of the requested action or actions. 

The menu DEX.DISP is reached by entering the menu item 
DISPLAY from the menu DEX. MAIN, and is used to display at 



14 



$ENTER AN ITEM FROM MENU - DEX.MAIN 
display menu all 



$ + + 

$ + MENU + 

$ + DEX.DISP + 

$ + + 

$ 1 + MENU + 

$ + + 

$ 2 + NEWS + 

$ + + 

$ 3 + MODE + 

$ + + 

$ 4 + + 

$ + + 

$ 5 + + 

$ + + 

$ 6 + + 

$ + + 

$ 7 + + 

$ + + 

$ 8 + + 

5 + + 

$ 9 + + 

$ + + 

$ 10 + + 

$ + + 

$ 11 + + 

5 + + 

$ 12 + + 

$ + + 



MENU 

DB-TYPES 

INTEGER 

REAL 

ARRAY-RL 



+ + 

+ MENU + 

+ DBEDCMDS + 

+ + 

+ CREATE + 

+ STORE + 

+ DELETE + 

+ COMMENT + 

+ EXPLAIN + 

+ PRINT + 

+ DUMP + 

+ SET-TITL + 

+ GET-TITL + 
+ + 

+ DONE + 

+ + 

+ + 



MENU 

DEX.ALTR 

TERSE 

VERBOSE 

KEYBOARD 

GRAPHIC 

ECHO-ON 

ECHO-OFF 

DONE 



MENU 

DXYES-NO 

YES 

NO 



+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 

+ 



MENU + 
DEX.MAIN + 

LIBRARY + 

HELP + 

DISPLAY + 

ALTER + 

TIDY + 

OPEN-DB + 

EDIT-DB + 

CLOSE-DB + 

BEGIN + 

CONTINUE + 

SYSTEM + 

QUIT-DEX + 



Figure 2.1 The DEX Menus 
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the terminal a menu or list of menus, DEX news, or the cur- 
rent mode. The system can be operating in either the DEX 
mode or a module mode. After the item is displayed control 
is automatically is returned to the menu DEX. MAIN. The menu 
DEX.ALTR is reached by entering the menu item ALTER from the 
menu DEX. MAIN, and is used to alter the state of DEX. An 
example might be to change from verbose to terse messages. 
This menu unlike DEX.DISP maintains control until the user 
has entered all desired menu items. In this case control is 
not returned to DEX. MAIN until the user enters the menu item 
DONE. 

The menu DBEDCMDS contains the commands used to edit a 
DEX database. The menu DBEDCMDS is reached by entering the 
menu item EDIT-DB from the menu DEX. MAIN. The database edit 
commands will be discussed in Chapter 4. The menu DB-TYPES 
is used by the database edit routines to obtain the type of 
variable to be entered in the database. The menu DXYES-NO 
can be used by any routine to obtain a yes/no answer to a 
question . 

The DEX. MAIN menu item LIBRARY displays a list of the 
modules currently in the DEX library. The menu item HELP 
displays a help file written by the module author to explain 
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the operation of a given module. The menu item TIDY is used 
to clear the graphics screen. The menu items OPEN-DB, 
EDIT-DB, and CLOSE-DB are used for manipulating databases, 
and will be discussed in Chapter 4. The menu item BEGIN is 
used to begin execution of a module. Upon completion of the 
module control is returned to the DEX mode. The menu item 
CONTINUE is used to resume execution of a module after exe- 
cution of the module was interrupted by a user request to 
temporarily return to the DEX mode. The menu item SYSTEM is 
used to temporarily exit to the operating system, and the 
system command RETURN is used to return to DEX. Finally the 
menu item QUIT-DEX is used to terminate the DEX session. 



2 . 2 The Design Philosophy of the DEX System 

The design philosophy of the DEX system was to provide 
the user with the maximum flexibility, while still maintain- 
ing consistency through control of all interactions. 
Celotto in his work [Celotto, 1981] pointed out that "there 
are five characteristics of DEX which reflect the design 
philosophy of the system: 

1. The user is in the design loop. 
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2. The system allows the design process to be executed 
in more than one sequence. 

3. The system talks with the user in plain English. 

4. The system is forgiving. 

5. The system has multiple capabilities for input and 
output . " 

Let us explore each of these important characteristics. 



2 . 3 The User In the Design Loop 



The design process is iterative in nature, and there is 
not neccessarily one correct flow through the procedure. 
Computer programs allow the relatively quick completion of 
complex and time consuming calculations, but often only in 
the sequence preconceived by the program writer. DEX allows 
the user to be in the design loop so the user can choose the 
sequence in which individual modules are executed. This is 
accomplished through dynamic loading and starting of 
modules. Additionally the user may choose to modify the 
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output of one module before it is input to another module or 
written to its destination. Thus the user can control the 
sequence of flow through the design spiral, and modify or 
insert additional data between steps. 



2 . 4 Multiple Design Sequences 

The flexibility offered by DEX is enhanced by the use of 
menus to allow the user to control the flow of execution. 
Thus the user has a wide choice of paths to follow through 
the design process. A menu is a list of options from which 
the user can choose the next step in the process, or the 
next variable to be defined. At present DEX allows a maxi- 
mum of twelve items per menu, and a maximum of 25 menus. At 
any time the user can make a request to return to DEX from a 
module by typing the $ sign followed by the name of the 
desired menu and menu item. Menu names and menu items can 
be up to eight characters long with no embedded blanks. 

If the user is in the DEX environment, then DEX will 
prompt to enter an item from a DEX menu. If in the module 
environment, that is if the user has told DEX to begin a 
module, then the user will be prompted to enter an item from 
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one of the module menus depending on the point of execution 
of the module. If the user doesn't know the items in the 
menu, the menu items can be displayed by typing; 

$ display menu menuname 

Where $ indicates a request to return to DEX, display is a 
menu item from menu DEX. MAIN, menu is a menu item from menu 
DEX.DISP, and menuname is the name of the menu that you 
desire to be displayed. After reviewing the menu the user 
types ; 

continue 

which is an item from menu DEX. MAIN, and the user is 
returned to the prompting message for the menu item. The 
menu items are of three different types; 

1. Information - such as data needed for a module's 
execution 

2. Commands - such as BEGIN for begin calculation, or 
DONE indicating the desire to terminate execution 
of this module. 
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3. Other Menus - such as INPUT implying proceed to the 
menu INPUT which might have as its items the possi- 
ble sources of input. 

2 . 5 DEX Communicates with the user in plain English 

The messages and prompts which DEX gives the user are 
written in English sentences, and are designed to be as 



clear 


as 


possible. The 


responses which the user 


gives are 


items 


from the 


various 


DEX or 


Module menus. 


These menu 


i terns 


are 


also 


English 


words 


designed to be 


a logical 


response 


to the 


queries 


from DEX. 


Also the user 


can string 



together a series of menu items into a sentence which will 
cause DEX to match each word with the appropriate menu, 
resulting in a sequence of actions. Thus the interaction is 
very much like an oral dialogue. This makes the DEX system 
easier to learn as the dialogue is consistent. 



2 . 6 DEX is Forgiving 

Because of the complexity of DEX, the occurrence of 
errors is inevitable. Whether it be simply typing something 
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that DEX does not expect, or the attempt to load a program 
that does not exist. The designers of DEX tried to antic- 
ipate as many errors as possible. And where possible, diag- 
nostic messages in plain English were included in the DEX 
message pool. Where possible, DEX advises the user of the 
error and then allows another try at the same place. If 
this is not possible DEX will return control to a previous 
routine or menu or back to DEX itself. In the event of a 
fatal error this investigator has added the capability to 
intercept the abort to the operating system, returning con- 
trol to a DEX fatal error handling routine. This routine 
announces the problem to the user, saves any open database, 
and gives the user the option of terminating execution (re- 
commended since the status of the system is unknown), or 
continuing execution until things have deteriorated beyond 
recovery . 



2 . 7 DEX has Many Sources/Destinations for Information 

In Celotto's work [Celotto, 1981], he used the term "in- 
formation" rather than input or output, because the terms 
"input", and "output" are too limiting in concept. He rath- 
er talked of "sources" of information, and "destinations" of 
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information. This writer will adopt the same convention. 
DEX enables the communication of information by the dynamic 
allocation of databases and files. DEX distinguishes 
between two types of files, a.) databases, and b.) disk 
files. In addition to these two types of files, DEX can 
communicate information to and from the terminal {or 
plotter) in the form of alphanumeric characters or graphics. 
The terminal is the destination for DEX messages, and the 
source for menu entries by the user. The DEX operating 
environment can be seen to have five sources of information 
and four destinations; they are; 

1. DEX - created and edited databases which can be 
saved on or loaded from disk. 

2. The user at the terminal using DEX utility routines 
to read or write alphanumer ics . 

3. The user at a graphics device using DEX graphics 
routines to read or create x-y co-ordinate plots, 
or other graphical data. (This capability has not 
yet been implemented in the present version of DEX 
at MIT. ) 
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4. Sequential disk files. 



5. Module default data (source of information only). 

The reader is referred to the work by Celotto[ [Celotto, 
1981] for a more detailed description of how to run DEX, and 
of the Extended DEX library of utility routines. A 
description of the DEX database system will be given in 
Chapter 4. 
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CHAPTER 3 



THE DEX ASSEMBLY LANGUAGE UTILITIES 
3 . 1 General Description 

As previously stated the philosophy of DEX is to provide 
the most flexibility to the designer using DEX, while still 
maintaining uniformity of dialogue and consistent informa- 
tion transfer. As a result DEX is a complex but structured 
program. Since the user is in the design loop, DEX has no 
way of knowing in advance the path that the user will follow 
through the design sequence. For this reason it cannot be 
determined in advance which files the user will need access 
to, or which modules the user will need loaded. Addi- 
tionally the user may start using a database which might 
become full, and need to be expanded. 

As a result, if all of the possible combinations were 
attempted to be provided for when DEX was compiled, the size 
and cost of DEX would be prohibitive. It would not be fea- 
sible to attempt such an undertaking, even if the resources 
were available. For this reason there are several functions 
which are essential to the dynamic nature of DEX. They are: 
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1. Dynamic file management. 



2. Dynamic loading and unloading of modules. 

3. Dynamic allocation of storage. 

4. Error recovery. 

Additionally there are several cosmetic or accounting capa- 
bilities that would enhance the DEX environment. These are; 

1. Obtaining time from the system, 

2. The obtaining of a users ID for communication and 
accounting of DEX use. 

3. The ability to interrupt DEX, go to the system to 
perform some function, and then return to DEX at 
the point where you stopped. 

4. The ability to shift the contents of a memory 
location either left or right. 
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However, these types of functions are generally not avail- 
able to the IBM/370 Fortran programmer, and therefore it was 
necessary to develop them in assembly language at MIT. The 
description of each of these capabilities are given in the 
subsequent sections. The code listings for the assembly 
language routines are included in Appendix C. 



3 . 2 Dynamic File Management 

In the traditional program organization the input/output 
files must be allocated to the logical unit number either 
before the program is executed or in an "open" statement in 
the program. This results in a fixed file structure, with 
the unit number being allocated to one file and one file 
only for the entire execution of the program. In the DEX 
System, it is unknown which modules the user will invoke, 
and therefore what files will need to be allocated to which 
units. DEX requires the dynamic allocation of files at exe- 
cution time, in order to provide the capability to change 
file allocation at any time. Also it is necessary for DEX 
to be able to check the existence of a file before attempt- 
ing to allocate it. DEX needs to be able to CLOSE files 
after use and free the allocation, so that the unit can be 
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used for other files. Before allocating a file DEX must be 
able to determine if a file is already attached to the 
desired unit, and if so what file. The following is a list 
of the assembly language routines used for dynamic file man- 
agement ; 

• ALLOC - Allocate a file for read or write. DEX 
allocates logical unit number (LUN) 18 as output 
device (OUTDEV) , and LUN 19 as input device 
(INPDEV). Other assignments of LUN used by DEX 
are : 



Messages device 


MSGSDV=13 


Usage device 


USEDEV=14 


Information device 


INFODV=17 


Database device 


DBSDEV=12 


News device 


NEWSDV=15 


Help device 


HELPDV=16 



• CKFILE - Check for the existence on the disk of a 
given file by its name. 



• CLOSE - Close an open file. 



• FREE - Free an allocated file. 
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• QUERY - Query what file if any is allocated to a 
given logical unit number (LUN). 

The routines ALLOC and CKFILE were existing routines mod- 
ified by this investigator. The routines CLOSE and FREE 
were existing routines which were not modified. The QUERY 
routine is a new routine developed by this investigator. 
The description of these routines is given in more detail 
below. 

ALLOC The routine ALLOC is a combination of the previous 
routines ALLOCW and ALLOC. It is used to allocate a fortran 
I/O file to a given unit number. A third argument has been 
added, which is a WFLAG (write flag) which if .TRUE, tells 
the routine to allocate the file for write with the pointer 
at the end of the file. ALLOC is an Integer Function. The 
calling sequence is, 

RET = ALLOC (LUN, FILENAME, WFLAG) 

Where, RET is assigned the integer value zero if the 
file was successfully allocated, and a non zero return 
code if the file could not be allocated. The current 
version of the MIT IBM operating system returns the 
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value 24 for all the error conditions, so that they 
cannot be distinguished. 

LUN is the Logical Unit Number which is the unit to 
which the module or DEX is writing or reading from. 
FILENAME is a 24 byte String containing the CMS name of 
the file, segregated into 8 byte pieces. If the 
filename is given as a '*', then the terminal is allo- 
cated. 

WFLAG is a flag which indicates that the file is to be 
allocated for write when it is .TRUE.. 

CKFILE The routine CKFILE is a logical function which checks 
the existence of a given file. This routine uses the 
FSSTATE macro which is a Conversational Monitor System (CMS) 
macro which checks the existence of a file. Error handling 
was added so the routine returns an RCODE to indicate the 
reason for a failure to find the given file. The calling 
sequence is. 



RET = CKFILE (FILENAME, RCODE) 

Where FILENAME is an 18 character string containing 
the full filename. 
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RET is a logical variable which is set .TRUE, if 
the file exists, and .FALSE, if the file does not 



exist . 

RCODE is an error return code of integer type. The 
meaning of the return codes are, 



RCODE = 0 


No error 


RCODE = 1 


Invalid character in FILEID 


RCODE = 2 


Invalid FILEMODE 


RCODE = 3 


File not found 


RCODE = 4 


Disk not accessed 


CLOSE The CLOSE routine 


was not modified by this investi- 



gator, but is included here for completeness. This routine 
closes a file for fortran to allow for file cleanup after 
use. The calling sequence is, 

CALL CLOSE (LUN,&NOTGOOD) 
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Where LUN is the Logical Unit Number to which the 
file to be closed is attached (the LUN is in full 
word binary) 

&NOTGOOD is for a fortran RETURN I convention. It 
is the label number of the line in the fortran rou- 
tine which called CLOSE where control will be 
returned if the CLOSE is not successful. This is 
accomplished in assembly language by returning a 0 
in register 15 if the normal return is to be taken, 
and a 4 in register 15 if the &NOTGOOD return is to 
be taken. For example; 

CALL CLOSE(18,&33333) 

RCODE = 0 
go to 99999 

C... The file could not be closed 

33333 RCODE = 1 



99999 RETURN 
end 



FREE The FREE routine was not modified by this investigator, 
but is included here for completeness. This routine frees 
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the 



file from the given LUN. The present version ignores 
the filename and frees whatever file is attached to that 
LUN. The calling sequence is, 

CALL FREE ( F I LENUM< , F I LENAME> , &NOTGOOD ) 

Where FILENUM is the LUN in character format 

FILENAME is the name of the file to be freed; it is 
currently ignored. 

&NOTGOOD is for the fortran RETURN I convention, 
and is as described in the CLOSE routine 
description above. 

QUERY The QUERY routine was developed by this investigator. 
The QUERY routine makes use of the RDJFCB (Read Job File 
Control Block) system macro, and the IBM CMS (Conversational 
Monitor System) macros CMSCB and DEVTYPE [IBM, 3,4,5]. When 
passed a fortran I/O unit number (UNIT), this routine reads 
the system Job File Control Block (JFCB) for FTNNFOOl, where 
NN = unit number. The JFCB contains information about any 
file which is attached to that unit number. The CMSCB macro 
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(CMS Control Block) is then used to map the JFCB. The CMSCB 
macro is a series of labeled fields with the same length as 
the fields in the File Control Block. These labels can then 
be used to extract data from the JFCB. The FCBREAD field is 
checked to see if a file was attached. If none is then a 
.FALSE. is returned. If a file is attached a .TRUE, is 

returned, and the FILENAME, FILETYPE, and FILEMODE are 
extracted from the JFCB and returned. The CMS DEVTYPE macro 
is invoked to determine the device type, and this is 
returned. The calling sequence is, 

TRUFLG = QUERY ( UN I T,RCODE, NAME, TYPE, MODE, DEV) 

Where UNIT is the fortran LUN for which infor- 
mation is desired. 

RCODE is a return code which is not currently 
used. It was included as an argument in the 
event that later changes in the system control 
block structure necessitated a return code to 
identify the reason for failure of the query. 

NAME is the filename returned. 
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TYPE is the filetype returned. 



MODE is the filemode returned. 

DEV is the device to which the unit is attached 
and is returned to the calling routine as an 8 
character device. The possible device returns 
are , 

PRINTER 

READER 

TERMINAL 

TAPE 

DISK 

PUNCH 

CRT 

If no file is attached to the UNIT then 
NAME, TYPE, MODE, and DEV are set to zero. 



3 . 3 Dynamic Loading and Unloading of Modules 

The dynamic loading and unloading of modules is an 
important feature of DEX, and is an integral part of 
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the system, providing much of DEX's flexibility. In 
the previous version of DEX at MIT dynamic unloading 
was not implemented, and dynamic loading was simulated 
by reserving a very large storage area at the time DEX 
was initialized. Then when a module was loaded it 
would always be loaded at the start of this area. This 
allowed modules to be dynamically loaded, but caused 
several problems. First it was necessary to waste 
storage, because the area had to be sufficiently large 
to hold the largest routine in the DEX library. Addi- 
tionally if two modules loaded were of different size 
and happened to use the same name for some of their 
routines, linkage conflicts could arise. This investi- 
gator developed the following assembly language 
routines to provide truly dynamic loading and unloading 
of modules. These routines make use of the OS/VSl 
supervisor services macros. [IBM, 6,7,8] 

• LOAD - Dynamically load a module into memory and 
return the entry point. 

• START - Dynamically start a loaded module. 

• UNLOAD - Unload a previously loaded module. 
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These routines will now be described in greater detail. 



load The LOAD routine loads a module into main storage and 
returns the entry point address. It uses the OS/VSl Super- 
visor 'Load' macro [IBM,?]. LOAD assumes the filetype is 
TEXT. LOAD calls the routine CKFILE with the filename to be 
loaded and a filetype of TEXT, to check that the file to be 
loaded exists. LOAD is a logical function, and if the load 
is unsuccessful a .FALSE. is returned. If the module is 
loaded, it's entry point is returned and LOAD is .TRUE.. 
This routine is used in Appendix A as an example. The call- 
ing sequence is, 

TRUVAL = LOAD (FILENAME, ENTRY, RFCODE) 

Where FILENAME is an 8 character filename, and 
a filetype of text is assumed. 

ENTRY is the returned entry point address where 
the module was loaded. 

RFCODE is a fatal return code which is set to 
one prior to entry. If no fatal error occurs 
the RFCODE is reset to zero. However, if a 
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fatal error occurs then execution terminates 
abnormally and RFCODE is still equal to one. 
This indicates to the DXABND routine that the 
error occurred in LOAD. 

The concept of a fatal return code introduced above, was 
introduced by this investigator to identify the routine in 
which a fatal error occurred. The fatal return code 
(RFCODE) is passed in common to the DEX abnormal end routine 
(DXABND). The routine DXABND will only receive control if 
an abnormal end has occurred. The value of the RFCODE when 
DXABND receives control indicates the routine where the 
error occurred. Prior to calling any routine where a fatal 
error could occur RFCODE is set to the value assigned to 
that routine. Thus if a fatal error occurs control will not 
return normally but will go to DXABND with the RFCODE still 
set. If the routine terminates normally then the RFCODE can 
be reset to zero. Currently only four RFCODES have been 
assigned. It was decided that further assignments of 
RFCODEs could be made as experimentation with DEX indicated 
the need. The current assignments are: 

RFCODE =0 No Fatal Error 
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RFCODE = 1 



Logical Function LOAD 



RFCODE = 2 Subroutine START 

RFCODE = 3 Logical Function FREEMN 

RFCODE = 4 Module program 

START The START routine when passed a module entry point 
(which was obtained using LOAD) passes control to that rou- 
tine, and then returns control to the calling routine after 
the module has completed. In other words, it provides link- 
age between DEX and the module program. The calling 
sequence is. 



CALL START (ENTRY, RFCODE) 

Where ENTRY is the entry address for a module 
as obtained from the LOAD routine. 

RFCODE is a fatal return code which is set to 
two prior to calling this routine. If no fatal 
error occurs then RFCODE is set to zero before 
returning to the calling routine. If a fatal 



39 



error 



occurs then execution is terminated 



abnormally, and the RFCODE is still equal to 
two. This then indicates to the DXABND routine 
that the error occurred in START. 

UNLOAD The UNLOAD routine deletes a previously loaded module 
from main storage. The UNLOAD routine is a logical function 
and returns UNLOAD = .TRUE, if the unload is successful. If 
the indicated module can't be found then UNLOAD is returned 
as a .FALSE.. The UNLOAD routine uses the OS/VSl Supervisor 
'DELETE' macro [IBM,?]. The calling sequence is, 

TRUVAL = UNLOAD (FILENAME) 

Where FILENAME is an 8 character name of a mod- 
ule loaded using the LOAD routine. 

No fatal return is necessary as there is no 
fatal error condition. 
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3 . 4 Dynamic Allocation of Storage 



The traditional storage approach is that an array 
must be dimensioned statically to the worst case size. 
This is not only inflexible, but is wasteful of 
storage. In the DEX System the dynamic allocation of 

storage is essential to the very philosophy of the 
database, and it is expected that the allocation of 
storage should expand and contract with the data 
stored. This is important if DEX is to be a truly 

flexible design tool. 

• FREEMN - Free previously allocated storage. 

• GETMN - Get a block of main storage and return its 
entry point. 

• READEC Read a block of memory at a location offset 
from the beginning of an existing memory area. 

• WRITEC Write a block of data to memory at a 
location offset from the beginning of the memory 
area . 
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The routines FREEMN, and GETMN were developed by this inves- 
tigator to provide the dynamic storage allocation capability 
in the MIT version of DEX in a manner that would facilitate 
the future development of a dynamic database. The previous 
version was locked at 2000 words of main storage for the 
database and there was no capability to free the storage and 
get an enlarged storage area. The routines READEC and 
WRITEC were existing routines based on the previous imple- 
mentation which simulated the Control Data Corporation (CDC) 
ECS storage scheme, but with a fixed amount of storage. The 
basic structure is still the same, but in the current ver- 
sion the READEC and WRITEC routines were modified to take 
the pointer and length information describing the storage 
area as arguments. The routine GETMN is called to get a 
block of storage of any size up to the maximum size of 16 
million bytes. However, the system has imposed a currently 
authorized limit of 1 million bytes on the DEX account. 
This limit can be raised but as it is raised the system is 
slowed, and limits are placed on the use of DEX. The point- 
er to the storage area is returned and placed in common. 
This information is then used to manage the storage area, 
allowing a new area to be obtained, the old copied, and then 
the old released using the FREEMN routine. 
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FREEMN The routine FREEMN frees a block of storage via the 
system FREEMAIN macro. The number of words of storage and 
the pointer to the area to be freed are passed as arguments. 
The calling sequence is, 

FREFLG = FREEMN (NWORDS,POINTR,RFCODE) 

Where NWORDS is the number of words of storage 
to be freed. 

POINTR is an integer pointer to the start of 
the main storage area to be freed. 

RFCODE is a fatal return code which is set to 
three prior to entry. If no fatal error occurs 
the RFCODE is reset to zero. However, if a 
fatal error occurs then execution terminates 
abnormally and RFCODE is still equal to three. 
This indicates to the DXABND routine that the 
error occurred in FREEMN. 

FREFLG will be .TRUE, if the area is success- 
fully freed. The only reason that it would 
fail is if the size exceeds the allowed storage 
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size. This would cause an abnormal end which 
is trapped for. 

GETMN The routine GETMN acquires a block of storage via the 
system GETMAIN macro. The number of words of storage to get 
is passed as an argument. A pointer to the area is 
returned. The virtual storage area obtained by the GETMAIN 
macro begins on a doubleword boundary (see Appendix A-3.1), 
or a page boundary. The area is not cleared to zero when it 
is allocated. This routine does not need a fatal RECODE 
because the GETMAIN macro is invoked with a conditional 
code. If the storage size requested exceeds the allowed 
limit then the GETMAIN is ignored, and GETMN is returned as 
a .FALSE.. The calling sequence is, 

GETFLG = GETMN (NWORDS,POINTR) 

Where NWORDS is the number of words of storage 
to be acquired. 

POINTR is an integer pointer to the start of 
the main storage area. 
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READEC The routine READEC reads a block of storage from the 



simulated CDC Extended Core Storage (ECS) area obtained by 
the GETMN routine. The block of storage is read into a 
string (symbolic name) starting at the first byte. The 
block begins at a given offset from the start of the ECS 
area. This routine is used to read a stored array or com- 
ment from the ECS area. Comments are known to be of fixed 
length 64. Arrays are stored with the length of the array 
in the first location and the n elements of the array in the 
next n locations. The calling sequence is, 

CALL READEC ( STRING , OFFSET , LENWDS , ECSPTR , ECSLEN ) 

Where STRING is the symbolic name of the array 
where the words of data are stored as they are 
read . 

OFFSET is the number of words that the desired 
block is offset from the beginning of the ECS 
area pointed to by ECSPTR. 

LENWDS is the number of words of storage to be 
read (length in words). 
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ECSPTR is the pointer to the beginning of the 
ECS area. ECSPTR is returned by GETMN when it 
acquires the ECS area. 

ECSLEN is the length of the ECS area and is 
used to check that the request is not an 
attempt to access beyond the area. If it is 
the request is ignored and a return code of 4 
is returned in register zero. This check is 
included to make the routine general, but is 
presently redundant as DEX makes a check prior 
to calling READEC. The check is made in the 
routine DBAPTR that the NEXECS plus LENWDS does 
not exceed MAXECS . If it does DBAPTR is set 
.FALSE., and upon return to DBEDIT, the routine 
DBXECS is called to expand the ECS area. 

The READEC routine reads a block of storage LENWDS long 
starting at ECSPTR plus OFFSET into STRING. The sequence of 
action when using READEC to read a database array from main 
storage would be; first the pointer to the array relative to 
the start of ECS would be obtained from the database. Then 
READEC would be called with that offset and a length of one. 
The value returned would be the length of the stored array. 
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READEC would again be called, but with an array as the 
string location, OFFSET+1, and the length of the array just 
read with the previous READEC call. 

WRITEC The routine WRITEC writes a block of storage into the 
'ECS’ storage area obtained by the GETMN routine. A block 
of storage is taken from string and stored in the ECS area. 
The block is stored at the given offset from the start of 
the ECS area. This routine is used to write an array or 
comment into the ECS area. Comments are known to be of 
fixed length 64. Arrays are stored with the length of the 
array in the first location and the n elements of the array 
in the next n locations. The calling sequence is, 

CALL WRI TEC (STRING , OFFSET , LENWDS , ECSPTR , ECSLEN ) 

Where STRING is the symbolic name of the array 
whose contents are to be moved into the ECS 
area . 

OFFSET is the number of words that the block is 
to be offset from the location pointed to by 
ECSPTR. 
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LENWDS is the number of words of storage to be 
written (length in words). 

ECSPTR is the pointer to the beginning of the 
ECS area. ECSPTR is returned by GETMN when it 
acquires the ECS area. 

ECSLEN is the length of the ECS area and is 
used to check that the request is not an 
attempt to access beyond the area. It is han- 
dled in the same manner as in READEC. 

The WRITEC routine writes a block of storage LENWDS long 
from STRING into the ECS area starting at ECSPTR plus 
OFFSET. The sequence of action when using WRITEC to write a 
database array into main storage would be: First the next 
available ECS location would be determined from the variable 
NEXECS, then WRITEC would be called to write the length into 
the next available location. WRITEC would again be called 
to write a pointer to the previous block into the next 
location. A pointer back to the database entry would be 
written, and then WRITEC would be called with the array and 
LENWDS equal to the length of the array. 
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3.5 



Error Recovery 



As has been previously discussed, DEX is a very forgiving 
system. If the user enters a number in the wrong format, 
then DEX announces it and indicates which data items must be 
reentered. If the user is prompted for a menu item, and 
enters an incorrect response, DEX again indicates the error 
and allows the user to recover. However, there are some 
system functions which are not forgiving, and cause an 
abnormal termination, such as an error in a module which 
tries an illegal action. As a result a routine was devel- 
oped to trap the abnormal end condition in the system and 
reroute it to a DEX fatal error handling routine. 






ABTRAP - Intercepts abnormal te 
transfers control to the fortran 
(developed by this investigator). 
DXABND announces to the user that a 
mination has occurred, and gives 
option of saving any open database, 
the user the option of continuing 
the session. 



rmination, and 
routine DXABND 
The routine 
n abnormal ter- 
the user the 
It then gives 
or terminating 
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The routine ABTRAP uses the CMS macro HNDSVC to set up a 
trap for a supervisor call SVC 13 which is the command used 
by the CMS operating system to branch to the system abend 
routine. The HNDSVC macro sets up the trap with an address 
where control is to be transferred anytime the SVC 13 com- 
mand is issued. The address used for the trap is the label 
ABNORM in the ABTRAP routine. After the trap has been suc- 
cessfully set ABTRAP returns control to DEX and indicates 
successful completion by returning with ABTRAP .TRUE.. Then 
if at anytime later an abnormal condition arises, the oper- 
ating system takes control and issues an SVC 13 to call the 
system abend routine. This condition is intercepted by the 
trap and rerouted to the location ABNORM in the routine 
ABTRAP. This section of assembly language code clears the 
trap to prevent a recursive abend sequence, and branches to 
the DEX routine DXABND. DXABND is a fortran routine which 
informs the user of the abnormal end condition, checks the 
RFCODE to determine which routine caused the error , provides 
the opportunity to save any open database, and then gives 
the user the option of terminating or continuing the DEX 
session . 

The DXABND routine makes the least number of calls possi- 
ble because of the uncertain status of DEX and the operating 
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I 







system. The primary objective here was to save the database 
so that all would not be lost. However, if the user desires 
an attempt will be made to recover and continue operating. 
This action is not recommended because the user's virtual 
machine has been altered and the conditions will continue to 
deteriorate. The calling sequence is, 

TRUFLG = ABTRAP (DUMMY) 

DUMMY is a dummy argument to satisfy local fortran 
logical function convention that a function 
requires an argument. 



3 . 6 Other Utility Routines 



It would be beneficial for DEX to 
capabilities. It would be useful to 
fy the user's logon ID in order to 
DEX users, and also to include the 
message . 



have several other 
be able to identi- 
keep an account of 
name in the welcome 



Often it is 
return to the 



convenient, when 
system to check 



running a program, to 
something, or perform 
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some system function and then return to the program to 
resume execution. 

Because of the large range of possible functions 
which could be performed under DEX, it would be useful 
to have the date and time indicated on the record of 
each DEX session so that the chronology of the design 
could be kept. 

In assembly language coding it is sometimes neces- 
sary to convert from words of memory to bytes. This 
can be done by shifting the contents of the word to the 
left. Also some system macros return the results 
packed into a single register with an address portion 
and perhaps a length portion. This information can be 
more easily extracted by shifting the contents of the 
register to purge the undesired portion. Thus a rou- 
tine which shifts a word of memory a given number of 
bits would be useful. The assembly language routines 
which provide these capabilities are; 

• ISHIFT - To shift a word of memory left or right a 
given number of bits. 
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JGVMID - To obtain the users Logon ID from the sys- 
tem. 

SYSTEM - To exit to the system and then be able to 
return to DEX after completing the desired 
function. It should be noted that ONLY transient 
system commands, and commands which are 
nucleus-resident are possible. They are; 

The nucleus-resident CMS commands, 

CP GENMOD START 

DEBUG INCLUDE STATE 

ERASE LOAD STATEW 

FETCH LOADMOD 

The transient system CMS commands, 

ACCESS HELP RELEASE 

ASSGN LISTFILE RENAME 
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COMPARE 



MODMAP 



SET 



DISK OPTION SVCTRACE 

DLBL PRINT SYNONYM 

FILEDEF PUNCH TAPE 

GENDIRT QUERY TYPE 

GLOBAL READCARD 

• TIME - To obtain the time of day and date f 
system. 

These routines were developed by Jeff Rice, exc 
JGVMID which was developed by J. Graham of the MIT I 
tion Proccessing Service and are presented here f 
pleteness. The calling sequence is, 

CALL ISHIFT(WORD,NBITS) 

Where WORD is the word to be shifted 



rom the 

ept for 
nf orma- 
or com- 
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NBITS is the number if bits to shift. If it is 
positive the shift is to the left if negative 
the shift is to the right. 

CALL JGVMID(VMID) 

VMID is the user ID who is currently logged on 
and using this program. This is the return 
argument from the system, and is 8 bytes in 
length. 

CALL SYSTEM _ Branches to the CMS subset. 

CALL TIME (STRING) 

Where STRING is the symbolic name where the 
time and date are to be stored. The format is 
HH.MM.SS.TH YY/DDD. This routine uses the 
supervisor services macro TIME to get the sys- 
tem time, and then extracts the time/date 
information in the correct format. 
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CHAPTER 4 



THE DEX DATABASE SYSTEM 



4 . 1 General Description 

The DEX Database System identifies entries in the 
database using the name of the variable or datum as a 
key. The variable's location in the database is not 
important. When the variable is placed in the database 
or later needs to be located for data manipulation, its 
address is calculated using a "hashing" algorithm. The 
hashing algorithm translates the name (sometimes called 
a key) into a number which is uniformly scattered or 
randomized. This number is then used to determine 
where the element is to be stored [Donovan, 1972; 
Martin, 1977]. This technique and the logical and 
physical database structure will be explained in sec- 
tion 4.2. The formal description of the overall 
database structure is called a "schema" [Martin, 1977]. 
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4.1. 1 The DEX Database Philosophy 



The DEX Database System was designed to provide the 
user with the maximum flexibility in database manipu- 
lation. A new database can be constructed and used, or 
an existing database can be loaded and used, by either 
the module program, or the user using database manipu- 
lation menu items from the menus DEX. MAIN or DBEDCMDS. 
Opening a database means that it is opened in memory 
for manipulation. If it is a new database, then memory 
is initialized for it. If it is an existing database 
which is stored on disk, it will be loaded into memory 
if necessary. No database will be loaded if a copy of 
the database requested already exists in memory. After 
the database has been created and used, it will not 
necessarily be saved on disk. DEX will prompt the user 
to determine if the user desires that the database be 
saved. Databases can be manipulated by either a module 
program or the user in the DEX environment. The possi- 
ble methods are: 

1. A database can be manipulated from within a module 
program using the database management routines 
directly, or using the Extended DEX Library. The 
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Extended DEX Library was created to facilitate the 
module author in handling different sources and 
destinations of information including databases. 
The reader is referred to the work by Celotto 
[Celotto, 1981] which gives a description of the 
Extended DEX Library routines, and how to use them. 
The basic DEX database management routines are: 

DBOPEN - Opens a database in memory. If the 
database is new memory is initialized for the 
new database. If the database already exists 
on disk it will be loaded into memory and used. 
DEX will not load a database if it is already 
in memory. 

DBVINS - Insert a new variable name (key) into 
an open database in memory. 

AGET - Retrieve real array values from the 
database in memory, and store them in the indi- 
cated array. (in all of the references to the 
database below the database is in memory) 
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IGET - Retrieve an integer value from the data- 
base for the given key, and store it in the 
indicated integer variable. 

CMTGET - Retrieve the comment associated with a 
given key, and store it in the indicated vari- 
able. The length of the comment can be up to 
64 characters. 

RGET - Retrieve a real value from the database 
for the given key, and store it in the indi- 
cated real variable. 

TGET - Retrieve the title of the open database, 
and store it in the indicated variable. The 
title can be up to 64 characters long. 

APUT - Store the values of an array in the 
database 

CMTPUT - Store the 64 character comment 
describing the datum (key). 



59 



IPUT - Store an integer value in the database 
for the given key. 

RPUT - Store a real value in the database for 
the given key. 

TPUT - Store a 64 character string into the 
database as its title. 

DBVDEL - Removes a variable name (key) from an 
open database by making the NODE where it is 
stored unavailable to the user. The NODE is 
flagged for later compression of the database. 

DBCLOS - Save the database on disk if the user 
desires, and close the database. 

2. The user can manipulate a database, while in the 
DEX mode, using database commands from the menus 
DEX.MAIN and DBEDCMDS. The Database Edit Commands 
menu (DBEDCMDS) is reached by entering the DEX.MAIN 
menu item EDIT-DB. The menu items on the menu 
DEX.MAIN which involve databases, and the routine 
called are: 
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OPEN-DB - calls DBOPUT - The DB Open Utility 
routine checks to see if there is already an 
open database. If there is the user is given 
the option of saving it. If the user wants to 
use a different database a name is obtained, 
and the user is given the option of using a 
saved database. If a saved database is to be 
used it is loaded into memory. If a new data- 
base is to be created the database memory area 
is initialized. 

EDIT-DB - calls DBEDIT - The routine DBEDIT 
prompts the user to enter an item from the menu 
DBEDCMDS. The Database Edit Commands are given 
below . 

CLOSE-DB - calls DBCLUT - The DB Close Utility 
routine announces the name of the open database 
if one exists, and gives the user the option of 
saving the database with the same or a new 
name. If the database cannot be saved this is 
indicated, and the user prompted for a differ- 
ent name. The database is then closed. 
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The Database Edit Commands from the menu DBEDCMDS, 
and the routine called when that command is entered 
are ; 



CREATE - calls DBEDCR - Creates a node in the 
database for the given data name or key. 

STORE - calls DBEDST - Obtains a value from 
the user for the given variable name or key, 
and puts it in the database at the previously 
created node. Valid types of data are integer, 
real, and one-dimensional real array. 

DELETE - calls DBEDDL - Removes a variable 
name (key) from an open database by making the 
NODE where it is stored unavailable to the 
user. The NODE is flagged for later com- 
pression of the database. 

COMMENT - calls DBEDCM - Puts a comment in the 
database describing the variable. For the pres- 
ent version of DEX where no provision has been 
made for units, it is desirable to include the 
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units in the comment. The comment can be up to 
64 characters in length. 

EXPLAIN - calls DBEDEX - Gets the variable's 
comment from the database, and displays it at 
the terminal. 

PRINT - calls DBEDPR - Prints the value stored 
for the given data name. 

DUMP - calls DBEDDM - Dumps the current con- 
tents of the database to the terminal. 

SET-TITL - calls DBEDTS - Prompts the user to 
enter a database title of up to 64 characters 
in length, and stores it in the database. 

GET-TITL - calls DBEDTG - Gets the title of the 
database from the database, and displays it at 
the terminal. 

DONE - Returns control to the DEX major control 
routine DXMAJC which prompts the user to enter 
a menu item from the menu DEX. MAIN. 
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A very important feature of the EDIT-DB capability, 
is that the user can edit a database while in the DEX 
environment or mode, but outside of the module, so that 
the user can modify the results generated by a program, 
before proceeding to the next module used in the design 
sequence. The DBEDIT routines are a substructure of 
DEX proper, and they are reached from the DEX mode by 
entering the menu item EDIT-DB from the menu DEX. MAIN. 
If the database has not been opened, the user would 
first enter the menu item OPEN-DB from the menu 
DEX. MAIN to open the database. The menu item EDIT-DB 
is one of the DEX commands, and transfers control to 
the routine DBEDIT, which then prompts the user to 
enter a menu item from the menu DBEDCMDS, and asks for 
the name of the datum to be manipulated. The DBEDIT 
commands are listed above. 

After the user has completed editing the database, 
and has returned to the DEX prompt "enter an item from 
menu DEX. MAIN" there are many paths that might be 
taken. If the user has finished using the database, 
then he would enter the menu item CLOS-DB from the menu 
DEX. MAIN. DEX will then announce the name of the open 
database, and ask if the user wants to save it. If the 
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answer is yes, the user will be given the option of 
changing the name. The database will then be written 
to the disk, and the file closed. 



4 . 2 The DEX Database Organization 

For the reader to understand the operation of the 
DEX database, and the further developments made by this 
investigator, it is necessary to present the formal 
description of the database structure. The overall 
view of the database is called its "schema". Martin 
discussed different levels of description of data; 
[Martin, 1977] 

1. The Global Logical Database Description, or SCHEMA 
- This is the overall view of the logical layout of 
the data. This is the way that the data is 
normally perceived. 

2. Physical Database Description - A description of 
the physical layout of the data, and how it is 
actually stored. 
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The DEX Database SCHEMA is represented in figure 4.1. This 
is the overall logical view of the data that would be seen 
at the terminal if the user issued the DBEDIT command dump, 
which would dump the contents of the database to the termi- 
nal. The physical representation of the data is shown in 
figures 4.2 - 4.7, and is described in the following 
sections . 



4.2.1 The Physical Description of the DEX Database 

The physical description of the DEX Database, or how the 
data is actually stored, will now be considered. The pres- 
ent version of DEX allows up to 200 variables to be stored 
in the database. These variables can be one of three types: 
integer, real, or real array. If the type is real array, 
then the number of elements in the array and the actual 
array values are stored in a separate ECS array storage area 
which is dynamically allocated, and initialized to 2000 
words of memory. As the area fills it is expanded in incre- 
ments of 2000 words. A pointer to the array's location is 
stored in the value field of the variable in the database. 
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$TITLE; **SAMPLE DATABASE 



NAME 


TYPE 


VALUE 


COMMENT 


NCREW 


(I) 


100 


NUMBER OF CREW 


DIAMETER 


(R) 


**UNDEFINED** 


HULL DIAMETER (SQUARE FEET) 


POWER 


(A) 


ARRAY ( 7) 




SPEEDAR 


(A) 


ARRAY ( 1) 




LENGTH 


(R) 


0.46000E+03 





THE ARRAYS 

$NAME: SPEEDAR , LENGTH= 3 ( 1) 

$ 0.50000E+01 O.lOOOOE+02 0.20000E+02 

$NAME; POWER , LENGTH= 3 ( 7) 

$ 0.80000E+05 O.lOOOOE+06 0.15000E+06 

Figure 4.1 The Database SCHEMA, and Sample Data 



Each individual array can contain up to 200 elements. How- 
ever, once the array has been stored its length becomes 
fixed at the number stored, even if it is less than 200. 
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Figure 4.2 is a representation of the physical layout of the 
DEX Database. 



The actual physical structure of the database is a series 
of arrays representing the fields of the schema. If the 
database is an already existing one then the values of the 
arrays represented in figure 4.2 are loaded from a disk 
file. If the database is new, then the values of the arrays 
are initialized in the routine DBINIT when the database is 
opened. The initial values will be explained below. 

The KEY to the database (KEY is the field used to locate 
entries) is the variable name. The name is up to eight 
characters in length, and is stored in a two-dimensional 
array IDENT(I,J). The first four characters of the name are 
stored in IDENT(I,1), and the second four in IDENT(I,2). 
The value of the index I indicates the number of the node in 
the database. The IDENT array is initialized with blanks. 
The variable type is stored in the array NODTYP(I), which is 
initialized to all zeros. Next is the array DATUM(I), which 
will contain the value of the data element. If the variable 
is an array then the DATUM will contain a pointer to the 
location of the array in memory. The DATUM array is ini- 
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TITLE 



NAVA I L 


DELCNT 


MAXECS 


NEXECS 


PRECS 


1 


0 


2000 


1 


0 



BUCKET 


1 


2 


3 


4 


5 




31 


32 




0 


0 


0 


0 


0 




0 


0 



NODE 


IDENTl 


IDENT2 


NODTYP 


DATUM 


LINK 


LINKF 


CMTPTR 


1 






0 


0 


2 


0 


0 


2 






0 


0 


3 


0 


0 


3 






0 


0 


4 


0 


0 


4 






0 


0 


5 


0 


0 


5 






0 


0 


6 


0 


0 


6 






0 


0 

• 

• 

• 


7 

• 

• 

• 


0 

• 

• 

• 


0 

• 

• 

• 


199 






6 


• 

• 

• 

0 


• 

• 

200 


• 

• 

• 

0 


• 

• 

• 

0 


200 






0 


0 


0 


0 


0 



ARRAY STORAGE AREA 



Figure 



4.2 The physical Database 



Structure 
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tialized to zero. Next is the array LINK(I), it is 
initialized to the node number plus one. This is used ini- 
tially to indicate the next available node in the database. 
It is later used to link together variables with the same 
hash value. This will be made clear in an example which 
will follow. Next is the array CMTPTR(I), which will con- 
tain a pointer to a 64 character comment which is stored in 
the array buffer. The arrays are stored in a separate area 
of main storage which is obtained dynamically at execution 
time. The database main structure then is made up of the 
arrays IDENT(I,1), IDENT(I,2), NODTYP(I), DATUM(I), LINK(I), 
and CMTPTR(I). The index I is dimensioned 200 in the pres- 
ent version of DEX. In addition to this main 200 node 
database body there is the auxiliary storage area where the 
comments and arrays are stored. Also there is a title array 
which allows for a 64 character title of the database to be 
stored. The addressing scheme uses a hashing function which 
converts the name of the datum into a number. The resultant 
hashed numbers are uniformly distributed between 1 and 32. 
For example, if the name of the datum was length, then the 
hashing function would yield the result; 

HASH (LENGTH) =32 
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The hashing function will be described in more detail in the 
next section. The result of the hash is used as a pointer 
to an element in a 32 element array BUCKET{I). The BUCKET 
is used to contain a pointer to the node in the database 
where LENGTH is stored. Length is stored in the next avail- 
able node in the database which is indicated by the variable 
NAVAIL. NAVAIL is initially set to one. It is updated from 
the value of the LINK at the node which is currently the 
next available when the next datum is stored. 



4.2.2 The DEX Hashing Function 

The DEX hashing function uses the internal machine code 
values for each character in the KEY name, summing these 
codes up until the first blank is encountered. The result- 
ing number is truncated using the modulo function to obtain 
a number between 1 and 32. 



4.2.3 An Example of Editing the DEX Database 

In this section, an example demonstrating the inserting 
of several nodes in the database will be given. An example 
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DEX database editing session is given in Appendix B, and 
shows the interaction with DEX which was required to enter 
the variables described in this example in the database. 
The sample session is given for information only, and will 
not be discussed as this example is a description of the 
physical structure of the database. The hashing values used 
in this example are not necessarily those that would actual- 
ly result for these variables, but were chosen merely for 
discussion purposes. Figures 4.3, 4.4, and 4.5 will show 
how the database is changed as each entry is made. Figure 
4.6 will show the effect of deleting an entry from the data- 
base. Initially the database is as shown in figure 4.2. 

The first name to be entered is LENGTH. Its type is 
real. It is assumed for this example that for each datum 
entered DEX has already prompted the user for the datum name 
and type. This name is hashed and the routine DBHASH 
returns the value 32. The bucket of 32 is checked to see if 
there has been a previous entry. Since the value of 
BUCKET(32) is zero this is the first entry. Since NAVAIL is 
one, the next available NODE is NODE one. So LENGTH is 
entered in NODE one as follows: (see figure 4.3) 

N0DE=1 

NAVAIL=LINK(1)=2 
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LINK(1)=BUCKET(32)=0 
BUCKET ( 32 )=N0DE=1 
IDENT(1,1)=LENG 
IDENTd ,2)=TH 

N0DTYP=-2 The 2 indicates real type and the negative 
indicates that no data has been entered for this node. 

LINKF=-32 The LINKF of the first or only entry in a 
chain is used to contain the negative value of the BUCK- 
ET as a BUCKET pointer. A negative number is used to 
distinguish the BUCKET pointer from a forward LINK to 
another NODE. 

As a result LENGTH has been entered in NODE one of the data- 
base with a NODTYP of -2 to indicate real type with no value 
entered. The next available node has been set from the link 
of NODE one, and is NAVAIL=2. The LINK has been updated 
from the BUCKET to point to any other nodes with the same 
HASH value. In this case the LINK is zero indicating that 
there are no others. BUCKET(32) is now pointing to NODE 
one, and LINKF is pointing back to bucket 32. 
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TITLE 



SAMPLE DATABASE 



NAVA I L 


DELCNT 


MAXECS 


NEXECS 


PRECS 


2 


0 


2000 


1 


0 



BUCKET 


1 


2 


3 


4 


5 




31 


32 




0 


0 


0 


0 


0 




0 


1 



NODE 


IDENTl 


IDENT2 


NODTYP 


DATUM 


LINK 


LINKF 


CMTPTR 


1 


LENG 


TH 


-2 


0 


0 


-32 


0 


2 






0 


0 


3 


0 


0 


3 






0 


0 


4 


0 


0 


4 






0 


0 


5 


0 


0 


5 






0 


0 


6 


0 


0 


6 

• 




• 


0 


0 


7 

• 

• 

• 


0 

• 

• 

• 


0 

• 

• 

• 


199 






6 


6 


• 

• 

200 


• 

• 

• 

0 


• 

• 

• 

0 


200 






0 


0 


0 


0 


0 



ARRAY STORAGE AREA 



Figure 4 



3 Length is entered 



in the database. 
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TITLE 



SAMPLE DATABASE 



NAVA I L 


DELCNT 


MAXECS 


NEXECS 


PRECS 


3 


0 


2000 


1 


0 



BUCKET 


1 


2 


3 


4 


5 


• • • 


9 




31 


32 




0 


0 


0 


0 


0 


• • • 


2 




0 


1 



NODE 


IDENTl 


IDENT2 


NODTYP 


DATUM 


LINK 


LINKF 


CMTPTR 


1 


LENG 


TH 


-2 


0 


0 


-32 


0 


2 


DIAM 


ETER 


-2 


0 


0 


-9 


0 


3 






0 


0 


4 


0 


0 


4 






0 


0 


5 


0 


0 


5 






0 


0 


6 


0 


0 


6 






0 


0 


7 

• 

• 

• 


0 

• 

• 

• 


0 

• 

• 

• 


199 


• 




• 

0 


6 


• 

• 

200 


• 

• 

• 

0 


• 

• 

• 

0 


200 






0 


0 


0 


0 


0 



ARRAY STORAGE AREA 



Figure 4.4 Diameter is entered in the database 
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TITLE 



SAMPLE DATABASE 



N AVAIL 


DELCNT 


MAXECS 


NEXECS 


PRECS 


5 


0 


2000 


1 


0 



BUCKET 


1 


2 


3 


4 


5 


• • • 


9 




31 


32 




0 


4 


0 


0 


0 


• • • 


3 




0 


1 



NODE 


IDENTl 


IDENT2 


NODTYP 


DATUM 


LINK 


LINKF 


CMTPTR 


1 


LENG 


TH 


-2 


0 


0 


-32 


0 


2 


DIAM 


ETER 


-2 


0 


0 


3 


0 


3 


HEIG 


HT 


-2 


0 


2 


-9 


0 


4 


SPEE 


DAR 


-3 


5 


0 


-2 


0 


5 






0 


0 


6 


0 


0 


6 






0 

• 

• 

• 


0 

• 

• 

• 


7 


0 

• 

• 

• 


0 

• 

• 

• 


199 


• 




• 

• 

• 

0 


• 

• 

• 

0 


200 


• 

• 

• 

0 


• 

• 

• 

0 


200 






0 


0 


0 


0 


0 



ARRAY STORAGE AREA 



Figure 4.5 Speedar 



is entered 



in the database. 
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TITLE 



SAMPLE DATABASE 



NAVA I L 


DELCNT 


MAXECS 


NEXECS 


PRECS 


5 


1 


2000 


1 


0 



BUCKET 


1 


2 


3 


4 


5 


• • • 


9 




31 


32 




0 


4 


0 


0 


0 


• • • 


2 




0 


1 



NODE 


IDENTl 


IDENT2 


NODTYP 


DATUM 


LINK 


LINKF 


CMTPTR 


1 


LENG 


TH 


-2 


0 


0 


-32 


0 


2 


DIAM 


ETER 


-2 


0 


0 


-9 


0 


3 


HEIG 


HT 


-9 


0 


2 


-9 


0 


4 


SPEE 


DAR 


-3 


5 


0 


-2 


0 


5 






0 


0 


6 


0 


0 


6 

• 






0 

• 

• 

• 


0 

• 

• 

• 


7 

• 

• 

• 


0 


0 

• 

• 

• 


199 






• 

• 

• 

0 


• 

• 

• 

0 


• 

• 

200 


• 

0 


• 

• 

• 

0 


200 






0 


0 


0 


0 


0 



ARRAY STORAGE AREA 



Figure 4.6 Height 



is deleted from the database. 
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TITLE 



SAMPLE DATABASE 



N AVAIL 


DELCNT 


MAXECS 


NEXECS 


PRECS 


7 


1 


2000 


13 


1 



BUCKET 


1 


2 


3 


4 


5 


• • • 


9 




31 


32 




0 


4 


0 


0 


6 


• • • 


2 




5 


1 



NODE 


IDENTl 


IDENT2 


NODTYP 


DATUM 


LINK 


LINKF 


CMTPTR 


1 


LENG 


TH 


-2 


0 


0 


-32 


0 


2 


DIAM 


ETER 


-2 


0 


0 


-9 


0 


3 


HEIG 


HT 


-9 


0 


2 


-9 


0 


4 


SPEE 


DAR 


3 


1 


0 


-2 


0 


5 


NCRE 


W 


1 


100 


0 


-31 


0 


6 


POWE 


R 


3 


7 


0 


-5 


0 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


• 


199 

200 


• 


• 


• 

0 

0 


• 

0 

0 


200 

0 


• 

0 

0 


• 

0 

0 



ARRAY STORAGE AREA 



1 


3 


2 


0 


3 


4 


4 


0.50000E+01 


5 


O.lOOOOE+02 


6 


0.20000E+02 


7 


3 


8 


1 


9 


6 


10 


0.80000E+05 


• 


• 



Figure 4.7 Array values are stored 
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The next variable to be entered is DIAMETER, which the 
user has indicated is of real type. Diameter is hashed and 
the routine DBHASH returns a value of 9. Since NAVAIL=2, 
DIAMETER will be entered in NODE two as follows: 

N0DE=2 

NAVAIL=LINK(2)=3 

LINK(2)=BUCKET(9)=0 

BUCKET(9)=NODE=2 

IDENT(2,1)=’DIAM' 

IDENT(2,2)=’ETER’ 

N0DTYP=-2 Indicating real type. 

LINKF(2)=-9 

As a result DIAMETER has been placed in the database at NODE 
two. The next available node has been updated from the LINK 
of NODE two such that the NAVAIL now is three. The LINK(2) 
has been updated from the BUCKET(9), and is equal to zero. 
The NODTYP is -2 to indicate a real number will be entered. 
Since this is the only datum that has hashed to BUCKET{9) so 
far LINKF(2) is set to point to BUCKET(9). 

The next variable entered is HEIGHT which is of real 
type. HEIGHT is hashed and the routine DBHASH returns a 

value of 9. When the BUCKET(9) is checked it is found that 
it contains a pointer to NODE two. This is a collision 
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since both items cannot occupy NODE two. Since NAVAIL=3, 
HEIGHT will be entered in NODE three, and will be connected 
to node two by the pointers LINK and LINKF as follows: 

N0DE=3 

NAVAIL=LINK{3)=4 

LINK(3)=BUCKET{9)=2 

LINKF(2)=NODE=3 

BUCKET(9)=NODE=3 

IDENT(3,1)='HEIG' 

IDENT(3,2)='HT ’ 

N0DTYP=-2 Indicating real type. 

LINKF(2)=-9 

As a result HEIGHT is entered into the database at NODE 
three, and NAVAIL is set equal to four. This time when 
LINK(3) is set equal to BUCKET(9), the value 2 is placed in 
the LINK. A pointer to NODE three is now placed in 
BUCKET(9). Since both HEIGHT and DIAMETER hashed to 
BUCKET{9) they are linked together. Thus BUCKET(9) points 
to HEIGHT in NODE three, NODE three is linked to DIAMETER in 
NODE two by LINK(3)=2, and DIAMETER in NODE two is linked to 
HEIGHT in NODE three by LINKF(2)=3. HEIGHT is linked to the 
BUCKET{9), to which both were hashed, by LINKF(3)=-9. 
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The next variable to be entered is SPEEDAR, which is a 
real array with 5 elements. SPEEDAR is hashed and the rou- 
tine DBHASH returns a value of 2. Since NAVAIL=4, SPEEDAR 
will be entered in NODE four as follows; 

N0DE=4 

NAVAIL=LINK(4)=5 

LINK(4)=BUCKET(2)=0 

BUCKET(2)=NODE=4 

IDENT(4,1)='SPEE' 

IDENT(4,2)=’DAR ' 

NODTYP=-3 Indicating real- array type. 

LINKF(2)=-2 

DATUM(4)=5 Indicating that 5 array elements will later 
be stored. 

As a result SPEEDAR is entered into the database at NODE 
four, and the NAVAIL is set to five. LINK(4) is updated 
from BUCKET(2) and becomes zero. BUCKET{2) is set to point 
to NODE four. The NODTYP is set equal to -3 which indicates 
that this entry is an array. The DATUM is set to the number 
of elements which the user expects to store in the array. 
When values are entered in the array, the actual number of 
elements that were entered will be stored followed by point- 
ers to the previous stored array, and a pointer back to the 
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NODE in the database. Then the actual elements of the array 
will be stored following these. 

At this point HEIGHT will be deleted from the database to 
show how this is done. The entry is deleted by setting its 
NODTYP=-9 The LINK of the deleted NODE replaces the LINK of 
the NODE pointed to by the LINKF of the deleted NODE. The 
LINKF of the deleted NODE replaces the LINKF of the NODE 
pointed to by the LINK. If the LINK is zero then this is 
the end of the chain. If the entry is the first entry after 
BUCKET, then the value of the deleted LINK is placed in 
BUCKET. The LINKF is handled as before except its value is 
the pointer back to the BUCKET. DEX knows that it is a 
pointer to the BUCKET and not to a NODE because it is nega- 
tive . 

In this example HEIGHT is deleted. So HEIGHT is hashed 
to BUCKET(9), which points to NODE three. The IDENT of NODE 
three is compared to the variable name, and since there is a 
match NODE 3 will be deleted. If there had been no match, 
each NODE in the chain would be searched for HEIGHT until a 
match occurred. The links are updated as previously 
described. The DATUM is set equal to zero, and the NODTYP 
is set to a minus nine to indicate the NODE has been 
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deleted. If the NODTYP is a +3 indicating that an array is 
stored, then the DATUM is set equal to -DATUM. Thus if the 
N0DTYP=-9 and the DATUM is less than zero, then the absolute 
value of DATUM is the pointer to the array storage block 
which must be compressed. The array storage area com- 
pression capability has not been implemented yet, and is an 
area for future work. A CMTPTR is handled similarlly. 

N0DE=3 

Since there is a LINK the LINKF of that NODE must be 
modified LINKF(2)=LINKF(3)=-9 

BUCKET(9)=LINK(3)=2 

DATUM(3)=0 If N0DTYP=3 then DATUM( I ) =-DATUM( I ) so that 
the pointer to the array storage area is saved for later 
compression of the array storage area. 

CMTPTR(3)=0 If CMTPTR is not 0, CMTPTR ( I ) =-CMTPTR (I ) 

LINKF(3)=0 

NODTYP=-9 Indicating that this datum has been deleted. 

It should be noted by the reader that at this point the 
variable names LENGTH, DIAMETER, SPEEDAR, and HEIGHT were 
created as NODES in the database only, and then HEIGHT was 
deleted as a NODE in the database. That is to say that the 
NODES are created, but no value has been stored for those 
datum names. To store a value, DEX prompts the user for the 
name, type, and value. The name is hashed to a BUCKET, and 
the NODE determined. If the NODE does not exist the user is 
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so informed. The NODE is checked to see if its IDENT 
matches the name, if it does then the value is stored in 
DATUM(NODE). If there is no match the next NODE in the 
chain is checked until a NODE is found with that name. Once 
the NODE containing the desired name has been located, its 
NODTYP is compared to the type indicated by the user. If 
the type does not match, then the user is informed and the 
user prompted for a new menu item. 

Figure 4.7 shows the database at a later stage after two 
additional variables and data for several of the variables 
have been entered. NODE five contains NCREW with a NODTYP 
of one indicating an integer value. Since the NODTYP is 
positive a value has been entered for this NODE. NODE six 
contains a real array POWER. Values have been entered for 
the two arrays SPEEDAR and POWER. The DATUM for SPEEDAR 
points to location one in the array storage area, and the 
DATUM for POWER points to location seven in the array stor- 
age area. Looking at the array storage area, the reader 
will notice that location one contains a three indicating 
that three numbers are stored. The next entry is a pointer 
to the previous stored array. This value is zero in this 
case because this is the first stored array. The next num- 
ber is a pointer to the NODE four, linking this array back 



84 



to the SPEEDAR entry in the database. This is followed by 
the three speeds which are the array entries. It should be 
noted that the user had originally said five numbers would 
be stored, but since only three were stored the size is now 
constrained to three, the number stored. The next number in 

the array storage is at location seven which is the begin- 
ning of the next array block. This number indicates that 

three values are stored in the array. Next is the pointer 

to the previous array which points to location one. This is 
followed by the pointer to NODE six to which this array 
belongs. The three array values follow in the next three 
locations (only one is shown). Looking at the figure 4.7 it 
is seen that DELCNT = 1 indicating one item has been deleted 
from the database. MAXECS = 2000 indicating that only one 
block of ECS storage has been obtained. NEXECS = 13 indi- 
cating that the next available location in the ECS area is 
at location 13. PRECS = 1 indicating that the previous 

array was stored beginning at location 1. The storage of 
comments is handled in a similar manner to the arrays. 

4 . 3 Further Developments in the DEX Database 

The DEX Database System as described in section 4.2 had 
the limitation of fixed size. It also lacked the capability 



85 



of compressing the database after delete or after some given 
number of deletes. The DEX Database System handled deletes 
by making the node available and setting the NODTYP = -9. 
This technique worked fine, except that it broke up the con- 
sistent upward flow of the LINKS, and if there were a large 
number of deletes would leave a lot of holes in the 

database. This would be detrimental to any future develop- 
ment of a dynamically extendible database. Another feature 
of the database is that it had pointers in one direction 
only. This made it more difficult to locate previous 

entries in the chain. The decision was made to modify the 
DEX Database System to be consistent with the possibility of 
future development in the flexibility of the Database 

System. To this end, it was decided to add the following 
capabilities to the already existing database. 

1. Bi-directional Pointers - To provide the capability 
of easily reconnecting the chain of LINKs after a 
delete. Also to provide possible future flexibili- 
ty in error recovery. This was done by adding to 
the physical database structure a forward link, 

LINKFd ) . 
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2. Modified Delete Structure - The delete technique 
was modified so that the node is not made available 
after delete. The next node and previous node in 
the chain are connected using the bi-directional 
link structure, and the deleted node made unavail- 
able by putting a -9 in the NODTYP. This provides 
a consistent link structure with the LINK always 
pointing backwards in the database, and the LINKF 
always pointing forward. This facilitates com- 
pressing the database. 

3. Database Compression Feature - As the database 
fills up it will have holes left by the now una- 
vailable deleted entries. Therefore, a routine 
(DBCMPR) was provided to compress the database when 
it is full or at the users request. This will also 
facilitate any future development in a dynamically 
extendible and contractable database. 

4. Dynamic Expansion of the Array Storage Area - Uti- 
lizing the dynamic memory management routines GETMN 
and FREEMN, the auxiliary array storage area was 
made expandable. As the 2000 word storage area 
fills up, a larger block of storage is obtained. 
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The current array area is copied into it and the 
first area released. 



4.3.1 The Pointer Structure 

The DEX pointer structure has been modified to include 
the original backward LINK(I), with the addition of the 
LINKF(I). When collisions occur in the database, and 
several nodes with the same hash value are chained together, 
then the direction of the links is as follows. The node 
address of the last item entered is placed in the bucket, 
and its LINK points back to the previous node that was 
entered with that hash value. The LINKF points forward from 
the previous node to the current one. The links are propa- 
gated along the chain in the same manner. The LINKF of the 
last node entered contains the negative of the bucket 
address to which it hashed. 



4.3.2 The Modified Delete Structure 

The delete structure was modified so that it would pre- 
serve the clean structure of the links. When a node is 
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deleted it is not made available but is flagged with a -9 in 
NODTYP. This will be used by the DBCMPR (compression rou- 
tine) routine. The next node in a chain and the previous 
node in the chain have their links joined together by using 
the LINK and LINKF of the deleted entry to tie them 
together . 



4.3.3 The Database Compression Feature (DBCMPR) 

The further capability to compress the database was 
developed so that as the database fills up, the database can 
be periodically compressed to open up any holes left by 
delete. The compress technique used was to search the data- 
base until a type of -9 was found. Then a count was updated 
to keep track of the number of deletes. The nodes were then 
moved up a number of positions equal to the count until the 
next -9 was encountered. As the Node is moved up its links 
were modified including any link to the bucket. 
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4.3.4 Dynamic Expansion of the Array Storage Area (DBXECS) 



With the further development of the DEX dynamic storage 
allocation achieved by this investigation, it has become 
possible to begin the development of the routines to allow 
the database storage to grow with the data. This investi- 
gator developed a simple first step routine to expand the 
database array area as it becomes full. The routine was 
called DBXECS for Database Expand ECS area. The routine has 
the following calling sequence, 

TRUVAL = DBXECS ( I DUM) 

The routine is a logical function with a dummy 
argument. The required variables are passed in the 
common DBDAIO which was modified to include the follow- 
ing variables: 

MAXECS - is the maximum ECS storage size. It is 
initialized to 2000 words, and is incremented by 
2000 each time the ECS area is expanded. 

NEXECS - is a pointer to the next free location in 
the ECS storage area. (as previously used) 
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PRECS 



- is a pointer back to where the previous 
array is stored in the ECS area. 

ECSPTR(2) - is an array containing the address of 
the old ECS area and the new ECS area. 

ECSLEN(2) - is the array containing the length of 
the two ECS areas. (ECSLEN(l) = MAXECS - 2000, 
ECSLEN(2) = MAXECS) 

The DBXECS routine is called as the array area is filled up. 
It acquires a new block of main storage whose size is now 
MAXECS+2000. It saves the current MAXECS and the previous 
MAXECS. It then copies from ECS area one to ECS area two, 
frees area one, and then saves the new pointer and maximums. 
It then returns to the calling routine. 

The DBSAVE and DBLOAD routines have been modified so that 
the final MAXECS, the NEXECS , and the PRECS are saved in the 
database . 
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4 . 4 Future Developments in the DEX Database 



The DEX Database System has been developed with the phi- 
losophy of the DEX System in mind. That is to provide the 
user the maximum flexibility while still maintaining con- 
sistency of structure, and uniformity of dialogue. The DEX 
Database System has been designed to use the usual DEX con- 
trol structure and menu communication system. It has also 
been designed with its future growth in mind. There are two 
major areas that need to be considered by future investi- 
gators. 

The first is to take the database the next step beyond 
the work of this investigator, and provide a dynamically 
extendible and contractable database that responds to the 
size of the database as it grows or items are deleted. This 
writer has taken a first step in this direction by providing 
the memory allocation routines, the capability to compress 
the database after delete (DBCMPR) , the capability to expand 
the array storage area (DBXECS), bi-directional LINKs, and 
the enhanced delete capabilities described in the previous 
section. However, the current version still has a limit of 
200 nodes in the main database structure. This limitation 
needs to be addressed, and a routine developed to make the 
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database completly expandible. Fagin in his work on "ex- 
tendible hashing" for dynamic database management has 
suggested a technique [ [Fagin , 1977] that provides a dynamic 
storage structure that grows and shrinks gracefully as the 
database grows and shrinks". 

The technique chosen by this investigator was to expand 
the database by acquiring more memory. This does not depend 
on the use of direct access file management, but has a limi- 
tation imposed by the amount of memory required. In the 
current version of DEX the size of the array storage area is 
limited by the number of nodes in the database and the size 
of array, overhead, and comment for each node. This is not 
an insignificant amount of storage, but is less than the 
theoretically available sixteen million. If the number of 
NODES in the database is also made expandible in memory, 
then the required storage could become unmanageable. Anoth- 
er technique which was considered, and temporarily set aside 
because of its machine dependencies, is Virtual Storage 
Access Method (VSAM) . This among other things allows direct 
access files on disk storage. With this procedure only the 
segments needed at any given time are in memory. Thus stor- 
age requirements would be kept at a manageable level. This 
would facilitate the use of Fagin' s technique of hashing to 
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a segment of the memory and then to a node within the page. 
The database could then be made totally expandible and 
contractable without large storage requirements. Both tech- 
niques will be experimented with and perhaps a combination 
of the two will be the best approach. The second area is to 
provide an alerting capability which allows for a structure 
that chains dependent variables to other variables upon 
which it depends. Then alert the user when a change has 
occurred in an independent variable upon which this variable 
depends . 
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CHAPTER 5 



CONCLUSIONS AND RECOMMENDATIONS 

The work of this investigation has provided a further 
enhancement of the already existing DEX capabilities, and 
has developed the structure necessary to achieve a truly 
dynamic database that can respond to the requirements of the 
complex design problem. 

This work has made improvements in the area of dynamic 
file management which provide a fairly adequate file manage- 
ment structure. Additionally the area of dynamic loading 
and unloading of modules has been solved by this investi- 
gators development of the LOAD, START, and UNLOAD routines 
utilizing supervisor services macros. The dynamic storage 
allocation routines and database enhancements have taken the 
database capabilities a step closer to the concept of an 
extendible database system that can dynamically respond to 
the growth of the database. 

There are several areas of DEX which still need develop- 
ment. First is the further development of the DEX database 
system to expand upon the work of this investigator to 
achieve a dynamically expandible database. Along this line. 
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the limit of 200 elements in the main body of the database 
must be addressed and the procedure developed to expand it. 
Future investigations will include experimentation with both 
dynamic memory allocation techniques to expand the database 
in memory, and Direct Access File Management techniques to 
expand the database in direct access files on disk, bringing 
only those segments needed into memory. It will be deter- 
mined which of these is the best procedure, or if a 
combination of the procedures is the best approach to remov- 
ing the database size limitations. The development of the 
dynamic storage allocation routines GETMN and FREEMN have 
provided the basic tools for this development, along with 
the modifications to the database system to make it upward 
compatible with the addition of a consistent bi-directional 
LINK structure. Finally with the database compress algo- 
rithm and the capability to expand the ECS storage area this 
work has taken the next step in the development of a truly 
dynamic database. 

Second is the implementation of the graphics capabilities 
into the MIT DEX environment. This capability is the log- 
ical next step in the development of DEX as a design system. 
The decision has been made to pursue segmented graphics as 
the base for the MIT implementation of DEX graphics. This 
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will allow the use of segmented graphics routines already 
implemented in DEX at other installations. 

In conclusion DEX then has been developed as a truly 
Design Executive with a strict adherhence to structured pro- 
gramming in its development. DEX follows the structured 
programming rule of one function for one routine with a con- 
sistent top down control structure. DEX allows the user to 
exercise as much or as little control over the design proc- 
ess as desired. With the dynamic file, memory, and module 
management capabilities coupled with the removal of 
restrictions from the DEX Database system and the future 
addition of a powerful graphics design capability will give 
the designer the maximum consistency and flexibility in the 
control of the flow of a design process. 
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APPENDIX A 



ASSEMBLY LANGUAGE PROGRAMMING 



A-1.0 Why Assembly Language 

The assembly language is the symbolic language which is 
most like the actual machine language. Machine language is 
the actual numerical codes and addresses stored in memory 
which the machine hardware translates into action. Depend- 
ing on the Computer, the machine language will be in Binary 
(base 2), Octal (base 8), or Hexadecimal (base 16). These 
numerical machine language codes provide control at the 
hardware level over machine functions, but are highly bur- 
densome and time-consuming. The advantage of assembly 
language over machine language is that it allows symbolic 
representation of instructions and addresses while still 
allowing just as much control over specific instructions and 
machine functions. 

The advantage of assembly language over high level lan- 
guages such as Fortran, Cobol, Algol, or PL/I is that the 
assembly language provides: [Madnick 1974, IBM, 2] 
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1. Full control over all machine functions. 



2. The form closest to machine language while still provid- 
ing symbolic representation. 

3. Ability to override system defaults assumed by the high- 
er level language. 

4. Ability to obtain system status information not accessi- 
ble by higher level languages. 

5. Ability to closely control your program down to the byte 
and even bit level. 

These advantages are very important in an executive manager 
program such as DEX, where it is important to know the sta- 
tus of the system, program modules, attached files, memory 
management, database management, and DEX requests by the 
user, so that these elements can be integrated and closely 
controlled. In this Appendix I will provide background on 
the general knowledge neccessary to writing assembly lan- 
guage code on any machine. I will then address the specific 
machine structure for the IBM/370 on which this version of 
DEX is written. I will then address the structure of an 
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assembly language program on the 370 (the general structure 
can be adapted to other machines), and explain in greater 
detail an example assembly language program from the utility 
routines written in assembly language for DEX. 



A- 2 . 0 General Approach to Preparing for a New Computer 

When preparing to write assembly language programs on a 
new computer, the programmer must gain an understanding of 
the machine's structure in order to control it. Madnick and 
Donovan [Madnick 1974] suggested a general approach to a new 
computer that could be adopted by a user wishing to under- 
stand the structure and become familiar with a new computer. 
The procedure consists of a series of questions that should 
be answered before attempting to write assembly language 
code on a new machine. 



1 . Memory 

What is the memory's basic unit, size, and address- 
ing scheme? 
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2. Registers 



How many registers are there? What are their sizes, 
functions, and interrelationships? 



3. Data 



What type of data can be handled by the computer? 
Can it handle characters, numbers, logical data? 
How is this data stored? 

4. Instructions 

What are the classes of instructions on the machine? 
Are there arithmetic, logical, symbolic 
instructions? What are their formats? How are they 
stored in memory? 

5. Special Hardware Features (pertinent to operating sys- 
tems ) 

The answers to questions 1,2,3, and 4 will provide 
sufficient understanding of the machine structure 
for most users. However, the user who must under- 
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stand the operating system in order to interface 
with it, such as the DEX system programmer (not 
neccessary for the DEX module programmer), must 
understand additional hardware features. 

a. Status of Program - How does the CPU keep track of 
which instruction to execute? Does the CPU differ- 
entiate between operating system state and user 
state? 

b. Input/Output Processing - How is input and output 
handled? If separate I/O processors are used, how 
does the CPU communicate with them? 

c. Interrupts - What kinds of interrupts exist? How 
are interrupts handled, and can they be intercepted? 
This is important in DEX for trapping abnormal ter- 
mination, control information, and other status. 

d. Masking - Can interrupts be ignored or suspended? 

e. Protection - Is there hardware available that can 
prevent the reading, writing, or execution of parts 
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of memory? Is it possible to access system routines 
for DEX use? 



f. Timers - Is there a clock on the system that can be 
accessed? 

g. States - Does the CPU have different states? Does 
the CPU have privileged instructions that may be 
executed only in certain states? 



To Madnick and Donovan's list I would add that the DEX sys- 
tem programmer must also gain an understanding of the oper- 
ating system control block structure [IBM, 3], Where control 
blocks are areas of storage in which the system keeps infor- 
mation on data blocks, file status, and executable module 
status. Also I would recommend that the DEX system program- 
mer become familiar with the system supervisor control 
program and how to communicate with it. The IBM/370 does 
this with the SVC (supervisor call) instruction [IBM, 4]. 



For the 370 
system programmer 



there are several references which the DEX 
should read [Madnick 1974, IBM, 1,2, 3, 4, 5] . 
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A- 3 . 0 IBM/370 Specific Machine Structure 



In this section I will answer the questions of section 
A-2.0 as they apply to the IBM/370. 



A-3 . 1 Memory 

The IBM/370 is a 32 bit word machine. The basic unit of 
memory is a byte = 8 bits. A word is composed of 4 bytes 
and each byte is individually addressable. Therefore each 
addressable position in memory contains 8 bits of informa- 
tion, where a bit contains either a binary one or zero. 
Instructions may operate on the following groupings of 
bytes : 



Memory Unit's 
Name 


No. of Bytes 


Length in Bits 


Byte 


1 


8 


Halfword 


2 


16 


Word 


4 


32 


Doubleword 


8 


64 
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The IBM/370 has a total of 2^^ bytes of memory (about 16 
million). The size is based on the addressing scheme used. 
The 370 uses a 24 bit address for referencing memory, and 
uses a base/offset addressing scheme. This scheme uses 12 
bits of a 32 bit instruction for the offset and 4 more bits 
to indicate a register that will be used as the base regis- 
ter. Into this base register is placed a 24 bit base or 
starting address. Another 4 bits of the instruction are 
used to reference a register used as an index register. The 
address is then calculated by adding the offset to the con- 
tents of the base register. If the storage area is an array 
the index register can then be used to reference the proper 
element in the array. 

Address = C(base register) + Offset + C(index register) 

where C(register) indicates the contents of register 

Any of the 4 bytes in a memory word can be individually 
addressed, but normally the low order byte is addressed. If 
the four bytes of the memory word had addresses 94,95,96, 
and 97 respectively, the memory word would be addressed as 
94. 
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A-3.2 Registers 



The 370 registers are of four general types: 

• 16 General Purpose 32 bit registers 

• 4 Floating Point 64 bit registers 

• 16 Special Control 32 bit registers 

• 1 Program Status Word 64 bit register 

The general purpose registers can be used as base address 
registers or for arithmetic or logical operations. When 
used as a base register they contain a starting address, and 
care should be used not to alter its contents after the 
desired address is stored. In the case of arithmetic and 
logical operations these registers act as scratch pads in 
which calculation results are accumulated, manipulated or 
compared. The floating point registers are used in floating 
point calculations where greater accuracy is required. The 
Program Status Word (PSW) contains the address of the 
instruction to be executed, as well as protection informa- 
tion, and interrupt status. 
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The 16 control registers are assigned to special operat- 
ing system facilities, such as paging or virtual memory han- 
dling. They are used, in a fashion similar to the general 
purpose registers, to act as scratch areas for the system 
facilities. They are used to hold information specifying if 
an operation can take place or to furnish and manipulate 
system information, such as the memory page size, for the 
control programs. The control registers are referenced by 
the numbers 0-15 in control instructions such as LOAD CON- 
TROL 13, LOCATION. 

There is no interrelationship on the 370 between the 4 
types of registers. Whithin a given register group, such as 
the general purpose registers, the registers are interre- 
lated by the instructions operating on them. 



A-3 . 3 Data 

All data and instructions are stored as binary ones and 
zeros. However, for convenience these numbers are written 
in the hexadecimal (base 16) number system. A hexadecimal 
digit is represented by four binary bits. The relation 
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between binary, hexadecimal and decimal numbers are given 
below ; 



Binary 


Hexadecimal 


Decimal 


0000 


0 


0 


0001 


1 


1 


0010 


2 


2 


0011 


3 


3 


0100 


4 


4 


0101 


5 


5 


0110 


6 


6 


0111 


7 


7 


1000 


8 


8 


1001 


9 


9 


1010 


A 


10 


1011 


B 


11 


1100 


C 


12 


1101 


D 


13 


1110 


E 


14 


1111 


F 


15 



So for example the binary number B’OOOO 0010 1111 1100' has 
the hexadecimal equivalent X’ 0 2 F C The 
bits in a memory word are numbered from left to right, with 
the left most bit numbered zero and the right most bit num- 
bered thirty one. The IBM/370 allows seven different data 
formats : 

1. Short Form Fixed Point - This format is a 16 bit 
halfword with bit 0 used as a sign bit. With a 
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binary zero indicating a positive number, and a 
binary one indicating a two's compliment negative 
number. A knowledge of binary arithmetic is 
assumed for this discussion [Osborne , 1980 ] . Bits 
1-15 are then an integer number. Some instructions 
are unsigned and treat the data as a 16 bit 
unsigned number. 



2 . 



Long Form Fixed Point - Similar 
except that bits 1-31 contain the 



to the short form 
integer number. 



3. 



Short Form Floating 
tation, with bit 0 
used as an exponent, 
tional number. 



Point - Is a 32 bit represen- 
used as a sign bit, bits 1-7 
and bits 8-31 used as a frac- 



4. 



Long Form Floating 
tation, with bit 0 
exponent, and bits 8- 



Point - 


I s 


a 64 


bit represen- 


used 


for 


sign 


, bits 1-7 for 


63 used 


for 


the 


fraction. 



5. Decimal-Number Formats - Decimal numbers may be 
represented in either of two formats, packed deci- 
mal or zoned (sometimes refered to as unpacked dec- 
imal) decimal. Either of these formats can have 
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from 1 to 16 bytes, with each byte consisting of 
two 4 bit codes. The packed decimal format is best 
suited for decimal arithmetic, while zoned decimal 
is best suited for input/output. 

a. Packed Decimal - In this format each byte con- 
tains two 4 bit decimal digits (0-9) with bina- 
ry representation 0000-1001, except for the 
right most byte which contains one binary deci- 
mal code and one 4 bit sign code in the right 
most 4 bits. The preferred sign code is 1100 
(hex C) for positive, and 1101 (hex D) for neg- 
ative. There are instructions which perform 
decimal arithmetic and return the results in 
the same format. There are also instructions 
which convert from packed decimal to zoned dec- 
imal (unpacked), or from packed decimal to 
binary . 

b. Zoned Decimal - In this format each byte con- 
tains a decimal digit in the right 4 bits and a 
zone code in the left 4 bits. The zone code is 
a hex F (1111 binary) which can easily be 
masked out to extract the decimal information. 
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In this format the zone of the right most byte 
is treated as a sign code with the same repre- 
sentation used in packed decimal. Zoned 
decimal digits are part of a larger character 
set which represents alphanumeric and special 
characters as two hexadecimal numbers. Thus 
the zoned decimal numbers are represented by 
the hex number "F" followed by a decimal digit 
between 0-9. The zoned decimal numbers are 
therefore best suited for the input, editing, 
and output of human-readable numeric data. 

6. Logical (Character) Format - In this 
representation, each character is represented by an 
8 bit code [IBM, 9] . 

A-3.4 Instruction Format 

The 370 has five types of instructions and five formats 
of instructions. The five types are: 

1. General Instructions - These are the arithmetic, 
logical, comparison, branching, memory and register 
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manipulating, data conversion, and mask and test 
instructions. 

2. Decimal Instructions - These are instructions which 
manipulate numbers which are in one of the decimal 
representations . 

3. Floating Point Instructions - These are the 
instructions which normalize, manipulate, and per- 
form floating point arithmetic. 

4. Control Instructions - These are the instructions 
which are used to control and manipulate the super- 
visor state. These are privileged instructions and 
cannot be executed from the problem state (that's 
the user program) . 

5. Input/Output Instructions - These are the 

instructions which are used to control the 

input/output operations on the machine. Generally 
the program writer will not access these 
instructions, but will instead access system macros 
designed to facilitate I/O. 
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The basic form of all of the different formats of 
instructions is an 8 bit Op Code, and two operands. In 
assembly language the 8 bit Op Code is represented with a 
mnemonic code, such as A for add or L for load. The Op Code 
operates on the two operands. Generally the flow is from 
the second operand into the first operand, except in store 
instructions where the data indicated by the first operand 
is stored in the location indicated by the second operand. 
An example of the first type of flow would be: 

A 1,2 

which would add the contents of register 2 to register 1 and 
leave the result in register 1. An example of the second 
type of flow would be: 

ST 5, TEMP 

which would store the contents of register 5 into the memory 
location which has the label TEMP. The five formats of 
instruction are: 

1. RR Format (2 bytes in length) - A register-register 
instruction which has an op code which operates on 
the contents of two registers. 
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2. 



RX Format (4 bytes in length) - A register-indexed 
memory instruction which moves the contents of a 
memory location into a register, stores the con- 
tents of the register in memory, or performs an 
arithmetic or logical operation on the contents of 
the register and the memory location. In this 
instruction the memory address is found by adding 
the offset, base, and index. 



3. RS Format (4 bytes in length) - A register-memory 
instruction which is similar to the RX instruction 
except that it has two register operands and a 
base/offset memory operand. 

4. SI Format (4 bytes in length) - An immediate oper- 
and - memory instruction which performs the opera- 
tion on the memory location and the immediate 8 bit 
value contained in the instruction. 



5. SS Format (6 bytes in length) - A memory-memory 
instruction which performs the operation on the two 
locations in memory. 



116 



A-3.5 Special Hardware Features 



STATUS OF A PROGRAM The program status word (PSW) is the 
internal register which is the basic control register for 
the 370. It contains information on interrupt status, what 
interrupts are masked out of use, whether the machine is in 
supervisor (privileged) state or problem state (working on a 
user problem), and the address of the next instruction. 



64 bits 



System 

Mask 


Key 


CMWP 


Interrupt 

code 


ILC 


CC 


Program 

Mask 


Instruction 

Address 


8 bits 


4 


4 


16 


2 


2 


4 


24 



bit 0 bit 63 



The SYSTEM MASK indicates whether 
accepted from a given channel. Bits 
nels 0-5 and must be on (binary one) 
accepted. Bit 6 set on indicates 
accepted from all channels above 6. 
external interrupts are allowed, 
masked (off) then the hardware will 
the interrupt is again enabled. 



or not interrupts will be 
0-5 correspond to chan- 
if interrupts are to be 
that interrupts will be 
Bit 7 on indicates that 
If the I/O channel is 
hold the interrupt until 
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The KEY is for protection of memory. I f an area of memo- 
ry is referenced its key must match the key in the PSW 
allowed for the executing program. If the keys do not match 
a protection exception occurs. 

The CMWP field is a collection of 4 flags (C=extended 
control mode, M=machine check mode, W=wait mode, P=problem 
state mode). C and M flags are used by the operating system 
for system control testing, and machine hardware failure 
checking. They will not be discussed as they are not appli- 
cable to the general assembly language programmer. The W 
bit indicates that the CPU is running (W=0) or waiting 
(W=l). The P flag indicates the state of the machine (P=0 
implies the supervisory state, P=1 implies the user problem 
is running). The INTERRUPT CODE tells the CPU the type of 
interrupt last received and thus where to go in memory to 
handle it. The ILC field is the Instruction Length Code and 
tells you the length of the previous instruction executed. 
The CC field is the Condition Code and contains the current 
value of the condition set by certain instructions. The CC 
field is tested by the conditional branch instructions, and 
is set to flag the results of arithmetic and comparison 
instructions. It might be set to indicate that the result 
of an operation was positive, negative, or zero. This con- 
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dition code can then be checked by a conditional branch 
instruction such as branch on zero (BZ). 

The PROGRAM MASK allows the masking of other non I/O 
interrupts such as underflow and overflow in arithmetic cal- 
culations. The INSTRUCTION ADDRESS contains the address of 
the next instruction to be executed. This field, the condi- 
tion code, and the previous instruction length code ILC are 
very useful for debugging programs. The load address of the 
program can be subtracted (in hex arithmetic) from the 
address in the PSW at the time of an error to get a relative 
address of the error. 

Of the special hardware features mentioned, the status of 
program, masking, and protection were covered in the above 
discussion of the program status word. Input/Output proc- 
essing and Interupts will now be discussed. 

Input/Output processing involves the transfer of informa- 
tion between the main memory of the computer and an I/O 
device such as a disk drive. On the IBM 370, I/O devices 
are attached to I/O processors called CHANNELS, which con- 
trol all data transfer. The CPU communicates with the I/O 
channels through the I/O instructions: 
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Test Channel 



Clear Channel 
Store Channel ID 
Clear I/O 
Halt Device 
Halt I/O 
Start I/O 

Start I/O Fast Relief 
Test I/O 

The first 3 instructions reference a channel only. The last 
6 instructions address a channel and a device on that chan- 
nel. The I/O address is a 16 bit address consisting of two 
parts. The leftmost eight bits is the channel address, and 
the rightmost 8 bits is the device address. There are up to 
256 channels numbered from 0-255, and their type and assign- 
ments are system dependent. Each channel has the facility 
for addressing up to 256 devices. The CPU uses the START 
I/O command to identify a channel and tell it to start oper- 
ation. The channel then loads the Channel Address Word 
(CAW) from a hardware fixed location in memory. The CAW 
contains the address in memory of the I/O program the chan- 
nel is to execute. 
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The programmer could write an assembly language program 
to control individual channels and devices. However, the 
system provides Data Management Macro Instructions which 
perform I/O operations, and provide the facilities to open, 
close, and manipulate files [IBM, 4], The reader is refered 
to the literature for a more detailed description of these 
facilities. [Madnick, 1974, Donovan, 1982, IBM, 1,2, 3,4, 5] 

Interrupts are hardware signals indicating that some con- 
dition requires the immediate attention of the CPU. On the 
370 there are five conditions or interrupt types; 

Operating Exception - tried to execute an illegal 
instruction. 

Machine Checking - Hardware Failure Detection 
External - such as an alarm 

Input/Output - channel is finished or waiting to 
transfer to CPU 

Supervisor Call (SVC) - request to the operating 
system. 
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An interrupt signal causes a hardware automatic response 
which notes where execution is when the interrupt occurs, 
and starts an interrupt action. When the interrupt occurs, 
the hardware first saves the current PSW in a predefined 
location in memory. Then the hardware loads the PSW from a 
specific reserved memory location, which depends on the type 
of interrupt. Then the CPU executes the interrupt handler 
program. When the interrupt handler completes its function 
it restores the old PSW from the fixed location. The CPU 
resumes execution of the interrupted program at the place 
where it was interrupted. 



A-4.0 Assembly Language Structure 

An assembly language program is made up of statements 
that are either instructions or comments. The assembly lan- 
guage instructions can be divided into three types: 

1. Machine Instructions (machine-op) 

Which are the symbolic representation of the machine 
language instruction. An example of a machine 
instruction would be the add instruction, in which 
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the CPU is instructed to add the contents of two 
registers. For example the machine instruction 



ADD 1,2 

would add the contents of register 1 to the contents 
of register 2. This type of instruction will be 
explained more fully in the example program. 

2. Assembler Instructions (psuedo-op) 

An assembler instruction or psuedo-op is a note to 
the assembler which is not executable at execution 
time, but rather tells the assembler how to set up 
the program while it is assembling it. Examples of 
this type of instruction would be DC, and DS which 
define constants or storage. Assembler instructions 
can also be used to define entry points and other 
references . 

3. Macro Instructions 

A macro instruction allows the assembler to substi- 
tute a predefined block of code for that macro sym- 



123 



bol when it is encountered in the program. This 
allows the user to define a block of code which is 
used often in a program as a macro. The name of the 
macro is then used in the program and the assembler 
expands it at assembly time. Macros can take argu- 
ments as well, and also allows for conditional 
expansion based on the arguments. The system pro- 
vides several utility macro definitions for 
Input/Output handling, data management, and communi- 
cation with supervisor operations. 

There are three types of comments in an assembly language 
program. In a macro definition comments must begin with a 
period in column one followed by an *. In the main part of 
the assembly language program comments on a line by them- 
selves must begin with an * in column one and must not go 
beyond column 71. Comments may be included on the same line 
as instructions, but must be after the last field of the 
instruction and must be separated from the last instruction 
field by at least one blank. 
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A-4 . 1 General Structure of Program 



The general structure of an assembly language program 
depends on the conventions of the particular machine you are 
using. The basic ideas will be the same as for the IBM/370 
but the reader will need to investigate these conventions at 
his computer facility. Generally psuedo-ops will be used to 
set up the entry and external linkage to the routine, as 
well as the starting reference and base register convention. 
Additionally psuedo-ops will be used to define storage 
areas. The general convention is that it is the responsi- 
bility of the assembly language routine to save all 
registers at entry, and restore them before returning con- 
trol to the calling routine. After this setup is 
accomplished the routine performs its calculations, stores 
its results, and returns to the calling routine. This 
structure will be explained in the example, and is summa- 
rized below: 

• Define program START, ENTRY points, control sectioning 
(CSECT,DSECT) , and external references (EXTRN) 
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• Identify the base register or registers the program will 
be USING. 

• Save the general purpose registers using the store mul- 
tiple(SM) instruction into the save area indicated by 
register 13. The store multiple instruction stores the 
contents of all the registers from the register indi- 
cated by the first operand to that indicated by the sec- 
ond operand into the memory area indicated by the third 
operand. 

• Pick up the arguments if any. The convention for pass- 
ing arguments will be explained in the section on coding 
conventions. 

• Perform the required calculations and operations. 

• Save the results in the arguments. 

• Restore the registers by using the load multiple 
instruction (LM) . This is neccessary because calcu- 
lations in your routine have changed the contents of the 
registers, and this could destroy the results obtained 
by the calling routine. Also if the registers aren't 
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restored the return path to the calling routine could be 
lost . 

• Return control to the calling program by branching to 
the address contained in register 14. (BR 14). 

• Use the END psuedo~op to end assembly. 



A-4 . 2 Coding Conventions 

The statement field in an assembly language program 
begins in column 1 and ends in column 71. Column 72 is used 
to indicate a continuation line follows. If a line is con- 
tinued then the continuation line begins in column 16. The 
format of an instruction statement consists of four parts 1) 
the label, 2) the operation code, 3)the operand entry, and 
4) an optional remark. The order is important, and must be 
from 1-4. The entries must be separated by one or more 
blanks. If used the label must begin in column 1, and the 
operation code must start at least one column to the right 
of column 1. Generally for ease of reading the op-code is 
placed in column 10, and the operands start in column 16 
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with the optional remark in any convenient place to the 
right of the operands. 

A-4 . 3 Subroutine Calling and Return Convention 

When calling an assembly language subroutine, the conven- 
tion is that the addresses of the arguments are loaded con- 
secutively into a parameter list (PLIST), with the address 
of argument one stored in the first word of storage, and the 
address of argument two stored in the second word and so on. 
Then the address of the parameter list is loaded into regis- 
ter one. For example assuming the two arguments NAME and 
RCODE : 



LA 3, NAME 



Load address of Name into R3 



ST 3, PLIST 



Store it in Plist 



LA 3 , RCODE 



Load address of Rcode into R3 



ST 3,PLIST+4 



Store it in the second word of 



PLIST 



LA 1, PLIST 



Load the Address of PLIST into 



R1 
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The convention for passing control is to load the address 
of the routine you want to branch to into register 15, and 
the address where you want control to return into register 

14. You then branch to the address in register 15. This 
can be accomplished nicely by use of the BALR (branch and 
link) instruction, which loads the address of the next 
sequential instruction into the first operand, and branches 
to the address contained in the second operand register. 
For example; 

L 15,CKADDR 

BALR 14,15 
CL 0,ZERO 

In this example the address of the CKFILE routine was previ- 
ously loaded into the location with the symbol CKADDR. The 
first instruction loads register 15 from the contents of 
location CKADDR. The BALR instruction loads the address of 
the compare logical (CL) instruction which follows it into 
register 14, and then branches to the address in register 

15. Now control has been passed to the CKFILE routine. 
When the subroutine has completed it's operation it does an 
unconditional branch to the address contained in register 14 
(BR 14) which returns control back to the CL instruction. 
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This CL instruction then compares the return code in regis- 
ter 0 to zero. 

Another convention often used is that register 13 con- 
tains the address of a save area for saving register con- 
tents. 

As the writer of an assembly language subroutine you then 
can expect the following register conventions when your sub- 
routine receives control. 

• Register 15 will contain the address at which your rou- 

tine has been loaded (since it was used to contain the 
address of the subroutine in the BALR 14,15 

instruction), and thus can be used as the base or refer- 
ence address register. 

• Register one will contain the address of a parameter 
list where the entries in the parameter list are point- 
ers to the arguments. There are two techniques for 
obtaining this data. Assuming that there are three 
arguments, the first technique would be to load multiple 
into registers 2, 3, and 4 from the location pointed to by 
register 1. 
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LM 2, 4, 0(1) 



Would result in registers 2,3, and 4 being loaded consec- 
utively from the address pointed to by register 1, C(l)+4, 
and C(l)+8. Each of these three registers would then be 
pointing at one of the arguments. To get the argument it is 
then neccessary to load from the address pointed to by the 
register. For example: 

L 5,0(2) 

This would load register 5 from the address contained in 
register 2 plus an offset of zero. The address contained in 
register two is the address of the first argument, which was 
loaded into register two by the load multiple instruction 
above. The other technique is to individually load each 
register with the address of an argument and then use that 
register to load another register with the actual argument. 
For example. 



L 2,0(1) load register 2 with the address pointed 
to by register 1, which is the first address in the 
parameter list. As a result register 2 will be 
pointing at the first argument. 
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L 5,0(2) load register 5 from the location pointed 
to by register 2. Places the first argument in 
register 5. 

L 3,4(1) load register 3 with the address pointed 
to by register 1 plus 4. In other words the point- 
er to the second argument. 

L 6,0(3) load register 6 from the location pointed 
to by register 3. 

L 4,8(1) again load register 4 from the location 
pointed to by register 1 plus 8. Register 4 will 
contain the address found by adding an offset of 8 
bytes to the address of the PLIST which is the 
address that was loaded into register 1. 

L 7,0(4) now register 4 points to the third argu- 
ment, and this instruction loads it into register 

7. 

• Register 13 will contain the address of a save area. 
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• Register 14 will contain the return address in the call- 
ing routine. 



A-4.4 



Macro Organization 



Macro definitions are composed of the MACRO psuedo-op 
indicating that a macro definition follows, a macro name 
which can take arguments, a body of executable assembly lan- 
guage instructions and conditional assembly macro 
instructions, and a MEND (Macro END) psuedo-op indicating 
that the macro definition has ended. Macro definitions must 
be either at the begining of a program or in a macro 
library. Arguments in the macro definition are indicated by 
& followed by a name. Wherever this occurs in the macro 
definition the corresponding argument will be substituted 
for it. Macros can be used for three basic functions. 



1. For Text Insertion - This is the most common use of 
macros. In this fashion macros are used to insert 
commonly used assembly language instructions into 
the source program at assembly time. This allows 
the programmer to not have to continuously write 
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repetitious code in each program. An example would 
be a macro to set up the linkage convention between 
subroutines, such as the DEX IN and OUT macros. 

2. For Text Modification - Modify the statements in 
the macro definition depending on how they are to 
be used. 

3. For Text Manipulation - Utilizing conditional 
assembly change the way a macro is expanded based 
on the arguments so that a different block of code 
is substituted in different situations. 



A-4 . 5 Example Assembly Language Routine 

In this section I will consider a specific assembly 
language subroutine from the DEX assembly language 
utility routines. The detailed analysis of this rou- 
tine will hopefully bring the readers understanding of 
assembly language programming into focus The routine 
that I will consider is the dynamic loading routine 
LOAD. This routine is a logical function. However, 
the passing of arguments will be the same as for a sub- 
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routine . 



The only difference is that in this case the 
truth value will be returned in register 0, with RO = 0 
indicating .false., and RO = 1 indicating .true.. The 
first thing you will encounter when looking at the LOAD 
routine in figure A-1, is the block of comments 
explaining its purpose and calling sequence. Comments 
are important in any programming language to insure 
that the understanding of the program is passed on, and 
to facilitate future maintenance and modification. In 
assembly language comments are absolutely essential in 
order to obtain any continuity of what was originally 
done and intended. 



After the comment section is the actual program 
code. The first line of which is the line - LOAD IN 
CSECT,etc.. This line is a macro definition, and the 
reader is referred to figure A-2 to see the expansion 
of the macro. The expanded code is indicated by a + 
sign in column 1. This is an excellent example of one 
of the reasons for using macros. All of the DEX assem- 
bly language routines have to save the registers and 
set up the base-using convention. This was done once 
when the IN macro was written and now is just invoked 
with each new subroutine. This macro and the OUT macro 
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which is further down in the code both take arguments 
which allow for modifying the use of the macro depend- 
ing on the situation. 

Looking at the expanded macro code in figure A-2, it 
can be seen that the first expanded instruction is the 
line - LOAD CSECT. In this line is the label LOAD and 
the psuedo-op CSECT. The CSECT defines to the assem- 
bler the beginning of this program as a control section 
which means it is executable and can be relocated. The 
routine is given the label LOAD. Another psuedo-op 
used to indicate a control section is the START 
psuedo-op, which is used at the start of the first rou- 
tine in a group of programs to be loaded into memory. 
All subsequent routines use the CSECT. The reason 
START was not used is that psuedo-op indicates the 
first control section in a block of source code. Since 
this routine is a logical function in DEX it is not the 
first routine in the source file, the CSECT was used to 
indicate this is a control section other than the 
first. A control section is the smallest block of code 
that can be relocated as a unit. 
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The next instruction encountered in the macro expan- 
sion is a branch to a location which is offset 10 from 
the contents of register 15. Since register 15 will 
contain the address of this routine when execution is 
transfered here the address is 10 (hex A) from the 
beginning of the program. This is in effect a branch 
to the STM instruction at statement number 34. This is 
neccessary because the macro expansion uses data con- 
stants (DC) at statements 32 and 33, and the CPU can't 
execute these since they are not instructions. The 
next instruction is the STM or store multiple which is 
used to save the registers in the location passed in 
register 13 + an offset of 12. The order in which the 
registers are stored in this case is register 14, 15, 
and then 1-12. After this the LR (load register) 
instruction is used to copy the contents of register 15 
into register 12 so that register 15 can be used for 
calling other routines. Thus register 12 now becomes 
the base register, and this is indicated by the USING 
psuedo-op which is a note to the assembler that it can 
use register 15 for the base register and it can assume 
that the address of LOAD will be loaded into it at exe- 
cution time. 
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At assembly time the assembler calculates its sym- 
bolic addresses relative to the address indicated by 
the USING psuedo-op. Thus looking at the excerpt from 
the listing (figure A-3) it can be seen that the 
address of the symbol NAME at statement 92 is 104 hex 
relative to LOAD. This then becomes the offset for the 
symbol NAME. Looking at the reference to NAME in 
statement number 42, the MVC (move) instruction: 

MVC NAME ( 8 ) , 0 ( 2 ) 

The instruction says to move 8 bytes of the contents 
pointed to by register 2 into storage location NAME. 
Looking to the left of the instruction at the object 
code column you will find a 12 digit hexadecimal number 
which is the machine code translation of this instruc- 
tion : 



D207 C104 2000 

The D2 is the op-code, the 07 is the length to be moved 
less one, the C104 is the first operand address, and 
the 2000 is the second operand address. Translating 
the two numbers using the IBM system/370 reference Sum- 
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mary card [IBM, 6], in the first operand the C is the 
base register (hex C = decimal 12) and the 104 is the 
offset. In the second operand the register is number 2 
and the offset is 000. Therefore all symbolic refer- 
ences are translated to a base register and the offset 
from the address in the USING instruction. 

Now continuing with the macro expansion of the IN 
macro, the next group of instructions loads the address 
of this routine's save area and then chains it to the 
one passed. The LA instruction at statement 37 loads 
register 15 with the address of the SAVEAREA argument. 
The next instruction at statement 38 stores the con- 
tents of register 13 into the location determined by 
adding 4 to the contents of register 15. This loads 
the address of the save area passed from the routine 
which called LOAD into LOAD'S SAVEAREA+4 . The next 
instruction at statement 39 saves the address of the 
old save area in SAVEAREA which is pointed to by regis- 
ter 15. Finally the instruction at statement 40 loads 
register 13 with the address of the new SAVEAREA. The 
last thing to discuss regarding to IN macro is the 
argument STORAGE=0. This argument indicates to the IN 
macro that no dynamic storage is to be allocated. If 
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desired the programmer could indicate by this argument 
that a block of main storage is to be allocated for use 
by this routine at execution of this routine. This 
completes the group of instructions resulting from the 
expansion of the macro IN (these are the instructions 
flagged by the +) . 

The next instruction at line 41 picks up the first 
argument in the parameter list by loading register 2 
with the pointer in register 1. Then the MVC instruc- 
tion which was explained in the paragraph on address 
translation above, moves the contents of the location 
pointed to by register 2 into the location NAME. The 
next instruction at line 43 loads the pointer to the 
third argument (rfcode) into register 3. Then the next 
MVC instruction moves a litteral "1" into the argument. 
This indicates that if a fatal error occurs it was in 
the LOAD routine. I f no fatal error occurs this code 
will be reset to zero before returning. 

The next group of instructions moves the address of 
NAME and RCODE into the parameter list and loads the 
address of the parameter list into register 1. This 
was discussed previously. Then register 15 is loaded 
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with the contents of location indicated by the label 
CKADDR. Looking at statement 100, the label CKADDR is 
defined using a DC (define constant) psuedo-op, and 
into this location is placed a V type constant. The V 
type constant is an external reference which will be 
resolved at execution time. the V constant tells the 
assembler to set up an external symbol table with the 
entry CKFILE. At execution time the address of CKFILE 
will be known and the address will be placed in this 
location. Thus the load instruction at line 51 is 
loading register 15 with the address of the subroutine 
CKFILE. This and the next two instructions were previ- 
ously discussed. The BALR 14,15 branches to the 
subroutine CKFILE because that will be the address 
loaded into register 15, and then links by placing the 
return address in register 14. Upon return register 0 
will contain a zero if CKFILE is .false, and a one if 
CKFILE is true. The CL (compare logical) instruction 
compares the contents of register 0 with the 0 stored 
in location ZERO. If the comparison is true the CC 
flag in the PSW is set, and the next instruction BE 
BOMB is a branch on equal. The BE tests the PSW and if 
the two were equal it branches to BOMB. This would be 
the case if the file which we are attempting to load 
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does not exist. If execution goes to BOMB, the fatal 
return code in argument 3 is reset to zero by use of 
the load and move instructions. Then the OUT macro is 
invoked with the arguments for a return register of 
zero and a return code of zero indicating a .false, 
condition. Thus if the routine calling load was an 
assembly language program, it will test register 0 for 
the return code. If the calling routine was a fortran 
routine, then this logical function LOAD will be 
.false. and the truthflg to which it is equated will 
be set .false . . 

If CKFILE was successful in finding the file to be 
loaded, then the next instruction encountered is the 
name of a system macro. This macro is called LOAD and 
takes the argument eploc=NAME. Which passes to the 
macro the name of the module being loaded. The system 
LOAD macro is expanded to three instructions. A load 
address (LA) of the NAME into register 0, a subtract 
(SR) register 1 from itself to zero it out(this indi- 
cates that we are not using a DCB or data control 
block), and SVC 8. The SVC instruction is a call to 
the supervisor program in the Operating System which 
indicates by the code 8 that the module name contained 
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in register 0 is to be loaded into memory. Upon return 
from the supervisor call the register 0 will contain 
the entry point location of the module in memory (the 
address). The contents of register 0 are then stored 
in the location ENTRY, and the rfcode is reset to zero 
by the same load argument address and move sequence. 
Also the contents of ENTRY is moved into argument 2. 
Then the OUT macro is invoked with a return code equal 
to one indicating that the LOAD was .true.. The OUT 
macro expansion allows for restoring the registers to 
the state they were upon entry, and then a BR 14 
returns to the calling routine. Where BR 14 is branch 
to the location in register 14, which is the next 
instruction in the calling routine. Also in the OUT 
macro is a LTORG psuedo-op which defines the place to 
put literal constants. A literal constant is of the 
form =F'l'. A literal can be used in an instruction as 
one of the operands, without having to define a storage 
location yourself. Literals are placed either at the 
end of the program, or at the location defined by the 
LTORG instruction. 

The last section of the program is the data constant 
area. In this area there are two types of psuedo-ops 
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used to reserve storage. The first is the define stor- 
age (DS) which reserves the indicated length of storage 
but does not set it to any initial value. An example 
of this is the SAVEAREA DS 18F, which saves 18 
fullwords of storage with the first labeled SAVEAREA. 
The other type is the define constant (DC), which sets 
the storage to the value indicated initially. Valid 
types are F for fullword H for halfword, X for 
hexadecimal, V for external address value, C for char- 
acter, B for binary, and A for address. 
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* LOAD - 

it 

SUBROUTINE TO LOAD A MODULE 

it 

* CALLING SEQUENCE ~ 

* 

* TRUTHVALUE = LOAD (FILENAME, ENTRY, RFCODE) 

it 

* WHERE FILENAME IS THE FILENAME OF MODULE TO BE LOADED. 

* THE FILETYPE IS ASSUMED TO BE TEXT SINCE THAT IS THE 

* ONLY TYPE WHICH CAN BE EXECUTED. 

* WHERE ENTRY IS AN INTEGER ENTRY POINT ADDR OF THE LOADED 

* MODULE TO BE RETURNED TO THE CALLING PROGRAM 

* WHERE RFCODE IS A FATAL RETURN CODE. ABNORMAL TERMINATION 

* IS ASSUMED AND RFCODE IS SET EQUAL TO ONE UPON ENTRY 

* TO THIS ROUTINE. IF ABNORMAL TERMINATION OCCURS 

* RFCODE = 1 INDICATES THE FAILURE OCCURED HERE. IF THE 

* TERMINATION IS NORMAL RFCODE IS SET TO ZERO PRIOR TO 

* RETURN TO THE CALLING ROUTINE. 

* 

* TRUTHVALUE IS TRUE IF LOAD WAS SUCCESSFUL AND FALSE IF 

* LOAD WAS UNSUCCESSFUL 

* 

* USES THE OS/VSl SUPERVISOR 'LOAD' MACRO. FOR FURTHER INFO 

* SEE 'OS/VSl SUPERVISOR SERVICES AND MACRO INSTRUCTIONS', 

* GC2A-5103 
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LOAD 


IN 


CSECT, STORAGE^ 


=0,SAVE=SAVEAREA 




L 


2,0(1) 


LOAD THE ADDR OF ARGl INTO R2 




MVC 


NAME (8) ,0(2) 


GET LOAD MODULE NAME 




L 


3,8(1) 


LOAD THE ADDR OF ARG3 INTO R3 




MVC 


0(4,3),=F’l' 


SET RFCODE = 1 LOAD CAUSED ANY FATAL ERR 




ST 


1 , TEMP 


SAVE Rl UNTIL AFTER LOAD 




LA 


3, NAME 


LOAD THE ADDRESS OF NAME INTO R3 AND 




ST 


3,PLIST 


STORE IT IN THE PARAMETER LIST 




LA 


3 , RCODE 


LOAD THE ADDRESS OF THE RETURN CODE IN R3 




ST 


3,PLIST+A 


AND STORE IT IN THE PARAMETER LIST 




LA 


1,PLIST 


LOAD Rl WITH PARAMETER LIST ADDRESS 




L 


15,CKADDR 


LOAD THE ENTRY ADDRESS FOR CKFILE 




BALK 


1A,15 


BRANCH TO ENTERY POINT 




CL 


0,ZERO 


COMPARE RETURN CODE IN RO TO ZERO 




BE 


BOMB 


IF RETURN CODE = 0 LOAD MODULE NOT FOUND 


it it it 









LOAD EPLOC=NAME 
ST 0, ENTRY 



1A5 



LOAD MODULE (EPLOC = ENTRY POINT LOCATION) 
STORE THE ENTRY POINT ADDR IN ENTRY 



( 





L 


1 , TEMP 


RESTORE R1 




L 


2,A(1) 


USE R2 FOR THE ADDR OF ARG2 




L 


3,8(1) 


USE R3 FOR THE ADDR OF ARG3 




MVC 


0(A,2) .ENTRY 


STORE THE ENTRY ADDR IN ARG2 


?v y? y» 


MVC 


0(A,3) .ZERO 


RESET RFCODE = 0, NORMAL TERMINATION 




OUT 


ST0RAGE=0,SAVE=SAVEAREA,RETC=1,RETREG=0 RETURN 'TRUE* 


*** 








Vr yc y? yr yc yr y? 
*** 


?vy?*ycyr* 


* 3V * yr * yr yr yr yr yr yr yr -k 


TEXT FILE DID NOT EXIST RETURN FALSE 


BOMB 


L 


1 , TEMP 


RESTORE R1 




L 


3,8(1) 


USE R3 FOR THE ADDR OF ARG3 




MVC 


0(A,3) .ZERO 


RESET RFCODE = 0, NORMAL TERMINATION 




OUT 


STORAGE=0,SAVE=SAVEAREA,RETC=0,RETREG=0 RETURN 'FALSE 


ycycyry? yryovyc 


yr yr yr yr yr yr 


k k k k k k k k k k k kk k 


k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k k 


*** CONSTANT AREA 




SAVEAREA 


DS 


18F 


AREA FOR SAVING THE REGISTERS 


TEMP 


DS 


F 


TEMPORARY ONE REGISTER SAVE AREA 


NAME 


DC 


CL8' ' 


FILENAME 




DC 


CL8'TEXT' 


FILETYPE 




DC 


CL2' ' 


FILEMODE 




DS 


OF 


ALLIGN ON FULL WORD BOUNDARY 


RCODE 


DS 


F 


RETURN CODE FROM CKFILE STORED HERE 


ENTRY 


DS 


A 


STORAGE AREA FOR MODULE ENTRY ADDRESS 


ZERO 


DC 


AX '00' 


ZERO FULL WORD FOR COMPARISON 


PLIST 


DS 


2A 


PARAMETER LIST 


CKADDR 


DC 


V(CKFILE) 


ENTRY POINT ADDRESS FOR CKFILE ROUTINE 




END 







figure A~1 



1A6 



1 
2 
3 
A 

5 

6 

7 

8 
9 
0 
1 
2 
3 
A 
5 

16 

17 

18 

19 

20 
21 * 
22 * 
23 * 
2A * 

25 * 

26 * 
27 * 



*jV***,v 
* 

* 

* 



.V .u 



* * * Vc * * * * * * * ;V * * * * Vc * Vc * * Vc Vc ?V * Vc ?V * * ?V * * Vc * Vc Vc * ?V * * * 5^: * Vr * * ?V ?V * Vr * 5 V * 

LOAD - 

SUBROUTINE TO LOAD A MODULE 
CALLING SEQUENCE - 

TRUTHVALUE = LOAD (FILENAME , ENTRY , RECODE) 

WHERE FILENAME IS THE FILENAME OF MODULE TO BE LOADED. 

WHERE ENTRY IS AN INTEGER ENTRY POINT ADDR OF THE LOADED 
MODULE TO BE RETURNED TO THE CALLING PROGRAM 
WHERE RFCODE IS A FATAL RETURN CODE. ABNORMAL TERMINATION 
IS ASSUMED AND RFCODE IS SET EQUAL TO ONE UPON ENTRY 
TO THIS ROUTINE. IF ABNORMAL TERMINATION OCCURS 
RFCODE = 1 INDICATES THE FAILURE OCCURED HERE. IF THE 
TERMINATION IS NORMAL RFCODE IS SET TO ZERO PRIOR TO 
RETURN TO THE CALLING ROUTINE. 

TRUTHVALUE IS TRUE IF LOAD WAS SUCCESSFUL AND FALSE IF 
LOAD WAS UNSUCCESSFUL 

USES THE OS/VSl SUPERVISOR 'LOAD' MACRO. FOR FURTHER INFO 
SEE 'OS/VSl SUPERVISOR SERVICES AND MACRO INSTRUCTIONS', 
GC2A-5103 



2g **** 5 ’; 


******yc*V; 


’ * * it it it it it it it it it it it it 


Vc it it Vc it it it it it it it it it it it it it it it it it it Vc it it Vc it it it it it Vc it it it it it it it it it it 


29 LOAD 


IN 


CSECT, STORAGE 


=0,SAVE=SAVEAREA 


30+ LOAD 


CSECT 




31 + 


B 


10(0,15) 


BRANCH AROUND ID 


32+ 


DC 


ALl (4) 


LENGTH OF IDENTIFIER 


33+ 


DC 


CL4' LOAD' 


IDENTIFIER 


34+ 


STM 


14,12,12(13) 


SAVE REGISTERS 


35+ 


LR 


12,15 




36+ 


USING LOAD, 12 




37+ 


LA 


15,SAVEAREA 


STATIC SAVE AREA 


38+ 


ST 


13,4(15) 


CHAIN OLD AREA IN 


39+ 


ST 


15,8(13) 




40+ 


LR 


13,15 




41 


L 


2,0(1) 


LOAD THE ADDR OF ARGl INTO R2 


42 


MVC 


NAME (8) ,0(2) 


GET LOAD MODULE NAME 


43 


L 


3,8(1) 


LOAD THE ADDR OF ARG3 INTO R3 


44 


MVC 


0(4,3) ,=F'l' 


SET RFCODE = 1 LOAD CAUSED ANY FATAL ERR 


45 


ST 


1 , TEMP 


SAVE R1 UNTIL AFTER LOAD 


46 


LA 


3, NAME 


LOAD THE ADDRESS OF NAME INTO R3 AND 


47 


ST 


3,PLIST 


STORE IT IN THE PARAMETER LIST 


48 


LA 


3 , RCODE 


LOAD THE ADDRESS OF THE RETURN CODE IN R3 


49 


ST 


3,PLIST+4 


AND STORE IT IN THE PARAMETER LIST 
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50 


LA 


l.PLIST 


LOAD R1 WITH PARAMETER LIST ADDRESS 


51 


L 


15,CKADDR 


LOAD THE ENTRY ADDRESS FOR CKFILE 


52 


BALR 


14,15 


BRANCH TO ENTERY POINT 


53 


CL 


0,ZERO 


COMPARE RETURN CODE IN RO TO ZERO 


54 


BE 


BOMB 


IF RETURN CODE = 0 LOAD MODULE NOT FOUND 


55 *** 








56 


LOAD EPLOC=NAME 


LOAD MODULE (EPLOC = ENTRY POINT LOCATION 


57+ 


LA 


0,NAME 


LOAD PARAMETER INTO REGISTER ZERO 


58+ 


SR 


1,1 


SHOW NO DCB PRESENT 


59+ 


SVC 


8 


ISSUE LOAD SVC 


60 


ST 


0, ENTRY 


STORE THE ENTRY POINT ADDR IN ENTRY 


61 


L 


1,TEMP 


RESTORE R1 


62 


L 


2,4(1) 


USE R2 FOR THE ADDR OF ARG2 


63 


L 


3,8(1) 


USE R3 FOR THE ADDR OF ARG3 


64 


MVC 


0(4,2) , ENTRY 


STORE THE ENTRY ADDR IN ARG2 


65 


MVC 


0(4,3) ,ZER0 


RESET RFCODE = 0, NORMAL TERMINATION 


66 *** 








67 


OUT 


ST0RAGE=0,SAVE=SAVEAREA,RETC=1,RETREG=0 RETURN 'TRUE' 


68+ 


L 


13,4(13) 


RETURN TO ORIGINAL SAVE AREA 


69+ 


LA 


0,1 




70+ 


ST 


0,20(13) 




71 + 


LM 


14,12,12(13) 




72+ 


BR 


14 




73+ 


LTORG 






74 




=F'i' 




75 *** 










TEXT FILE DID NOT EXIST RETURN FALSE 


y y Vc * 








78 BOMB 


L 


1 , TEMP 


RESTORE R1 


79 


L 


3,8(1) 


USE R3 FOR THE ADDR OF ARG3 


80 


MVC 


0(4,3) .ZERO 


RESET RFCODE = 0, NORMAL TERMINATION 


81 


OUT 


STORAGE=0,SAVE=SAVEAREA,RETC=0,RETREG=0 RETURN 'FALSE 


82+ 


L 


13,4(13) 


RETURN TO ORIGINAL SAVE AREA 


83+ 


LA 


0,0 




84+ 


ST 


0,20(13) 




85+ 


LM 


14,12,12(13) 




86+ 


BR 


14 




87+ 


LTORG 






8 8 ^ '' ' ^ ’ ' * * * * * ' * * ' * * * * * ' ' * ' ' " ' " ' ^ ' ' * * ^ 


89 *** data constant area 




90 SAVEAREA 


DS 


18F 


AREA FOR SAVING THE REGISTERS 


91 TEMP 


DS 


F 


TEMPORARY ONE REGISTER SAVE AREA 


92 NAME 


DC 


CL8' ' 


FILENAME 


93 


DC 


CL8 ' TEXT ' 


FILETYPE 


94 


DC 


CL2' ' 


FILEMODE 


95 


DS 


OF 


ALLIGN ON FULL WORD BOUNDARY 


96 RCODE 


DS 


F 


RETURN CODE FROM CKFILE STORED HERE 


97 ENTRY 


DS 


A 


STORAGE AREA FOR MODULE ENTRY ADDRESS 


98 ZERO 


DC 


4X ' 00 ' 


ZERO FULL WORD FOR COMPARISON 
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99 PLIST 

100 CKADDR 

101 



DS 2A 

DC V(CKFILE) 

END 



PARAMETER LIST 

ENTRY POINT ADDRESS FOR CKFILE ROUTINE 



figure A“2 
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EXCERPT FROM LISTING 



-SYMBOL 

LOAD 



- LOC 

000000 

000000 

OOOOOA 

000005 

000009 

OOOOOA 

OOOOOE 

000010 

000014 

000018 

OOOOIC 

OOOOIE 

000022 

000028 

00002C 

000032 

000036 

00003A 

00003E 

000042 

000046 

00004a 

00004E 

000050 

000054 



- LOC 
0 

000058 

00005C 

00005E 

000060 

000064 

000068 

00006C 



EXTERNAL SYMBOL DICTIONARY PAGE 1 
TYPE ID ADDR LENGTH LDID 
SD 0001 000000 000130 CKFILE ER 0002 

PAGE 2 

OBJECT CODE ADDRl ADDR2 STMT SOURCE STATEMENT 

29 LOAD IN CSECT,STORAGE=0,SAVE=SAVEAR 
30+LOAD CSECT 



47F0 FOOA 


OOOOA 




31+ 


B 


10(0,15) 


04 






32+ 


DC 


ALl (4) 


D3D6C1C4 






33+ 


DC 


CL4'L0AD' 


00 












90EC DOOC 


OOOOC 




34+ 


STM 


14,12,12(13) 


18CF 






35+ 


LR 


12,15 






00000 


36+ 


USING LOAD, 12 


41F0 C0B8 


000B8 




37+ 


LA 


15,SAVEAREA 


50DF 0004 


00004 




38+ 


ST 


13,4(15) 


50FD 0008 


00008 




39+ 


ST 


15,8(13) 


18DF 






40+ 


LR 


13,15 


5821 0000 


00000 




41 


L 


2,0(1) 


D207 C104 2000 


00104 


00000 


42 


MVC 


NAME (8) , 0 (2) 


5831 0008 


00008 




43 


L 


3,8(1) 


D203 3000 C090 


00000 


00090 


44 


MVC 


0(4,3),=F'l' 


5010 ClOO 


00100 




45 


ST 


1 , TEMP 


4130 C104 


00104 




46 


LA 


3, NAME 


5030 C124 


00124 




47 


ST 


3,PLIST 


4130 C118 


00118 




48 


LA 


3 , RCODE 


5030 C128 


00128 




49 


ST 


3,PLIST+4 


4110 C124 


00124 




50 


LA 


1,PLIST 


58F0 C12C 


0012C 




51 


L 


15,CKADDR 


05EF 






52 


BALR 


14,15 


5500 C120 


00120 




53 


CL 


0,2ER0 


4780 C094 


00094 




54 


BE 


BOMB 




PAGE 


3 








OBJECT CODE 


ADDRl 


ADDR2 


STMT SOURCE 


STATEMENT 




















56 


LOAD 


EPLOC=NAME 


4100 C104 


00104 




57+ 


LA 


0,NAME 


IBll 






58+ 


SR 


1,1 


0a08 






59+ 


SVC 


8 


5000 CllC 


OOllC 




60 


ST 


0, ENTRY 


5810 ClOO 


00100 




61 


L 


1 , TEMP 


5821 0004 


00004 




62 


L 


2,4(1) 


5831 0008 


00008 




63 


L 


3,8(1) 
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000070 


D203 


2000 


CllC 


00000 001 1C 


64 


MVC 


0(4,2) .ENTRY 


000076 


D203 


3000 


C120 


00000 00120 


65 

66 *** 


MVC 


0(4,3) .ZERO 


67 




OUT 


STORAGE=0,SAVE=; 


SAVEAREA,RETC=1,RETREG=0 RETURN 'TRUE 


00007C 


58DD 


0004 




00004 


68"'’ 


L 


13,4(13) 


000080 


AlOO 


0001 




00001 


69+ 


LA 


0,1 


00008A 


500D 


0014 




00014 


70+ 


ST 


0,20(13) 


000088 


98EC 


DOOC 




OOOOC 


71+ 


LM 


14,12,12(13) 


00008C 


07FE 








72+ 


BR 


14 


000090 










73+ 


LTORG 




000090 


00000001 






74 




=F’l' 












75 *** 

76 


TEXT FILE 


DID NOT EXIST 












it it it 


RETURN FALSE 












yy it it it 






00009A 


5810 


ClOO 




00100 


78 BOMB 


L 


1 , TEMP 


000098 


5831 


0008 




00008 


79 


L 


3,8(1) 


00009C 


D203 


3000 


C120 


00000 00120 


80 


MVC 


0(4,3) .ZERO 


81 




OUT 


ST0RAGE=0,SAVE= 


SAVEAREA,RETC=0,RETREG=0 RETURN ’FALSE 


0000A2 


58DD 


0004 




00004 


82+ 


L 


13,4(13) 


0000A6 


4100 


0000 




00000 


83+ 


LA 


0,0 


OOOOAA 


500D 


0014 




00014 


84+ 


ST 


0,20(13) 


OOOOAE 


98EC 


DOOC 




OOOOC 


85+ 


LM 


14,12,12(13) 


0000B2 


07FE 








86+ 


BR 


14 


0000B8 










87+ 


LTORG 





g g * * * Vf * Vc ?V Vc * ?V * Vf Vf it it it it it it it it it it it it it it it it 



89 *** DATA CONSTANT AREA 



0000B8 








90 


SAVEAREA 


DS 


18F 


000100 








91 


TEMP 


DS 


F 


000104 


4040404040404040 




92 


NAME 


DC 


CL8' ' 


OOOIOC 


E3C5E7E340404040 




93 




DC 


CL8 ' TEXT ' 


000114 


4040 






94 




DC 


CL2' ' 


000118 








95 




DS 


OF 


000118 








96 


RCODE 


DS 


F 


0001 1C 








97 


ENTRY 


DS 


A 


000120 


00000000 






98 


ZERO 


DC 


4X'00' 


000124 








99 


PLIST 


DS 


2A 


00012C 


00000000 






100 


CKADDR 


DC 


V(CKFILE) 










101 




END 




RELOCATION DICTIONARY 


PAGE 


4 






-POS.ID 


REL. ID 


FLAGS 


ADDRESS 








0 0001 


0002 


1C 


00012C 








CROSS-REFERENCE 




PAGE 


5 






-SYMBOL 


LEN 


VALUE 


DEFN 


REFERENCES 






BOMB 


00004 


00000094 


00078 


00054 








CKADDR 


00004 


0000012C 


00100 


00051 








ENTRY 


00004 


OOOOOllC 


00097 


00060 00064 
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LOAD 


00001 


00000000 


00030 


00036 






NAME 


00008 


OOOOOlOA 


00092 


000A2 


000A6 


00057 


PLIST 


OOOOA 


0000012A 


00099 


000A7 


000A9 


00050 


RCODE 


OOOOA 


00000118 


00096 


000A8 






SAVEAREA 


OOOOA 


000000B8 


00090 


00037 






TEMP 


OOOOA 


00000100 


00091 


000A5 


00061 


00078 


ZERO 


00001 


00000120 


00098 


00053 


00065 


00080 


LITERAL CROSS-REFERENCE 


PAGE 6 




SYMBOL 


LEN 


VALUE 


DEFN 


REFERENCES 




l=F'l' 


OOOOA 


00000090 


0007A 


OOOAA 







figure A-3 
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APPENDIX B 

A Sample DEX Database Editing Session 



start main 



EXECUTION BEGINS... 

DEX VERSION 82.1(35 98883) 

$DEX AT MIT WELCOMES USER CHRYSDX 

$ON 82/138 

$AT 14.39.27.00 

$THIS IS THE MAY 1982 DEX VERSION 
$ENTER AN ITEM FROM MENU - DEX. MAIN 
open-db 

$ENTER THE NAME OF THE DATA-BASE 
$FILE NAME 

$ENTER UP TO 24 CHARACTERS 
example database< 

$DO YOU WISH TO USE A PREVIOUSLY CREATED A DATABASE 
$ENTER AN ITEM FROM MENU ~ DXYES-NO 
no 

$ENTER AN ITEM FROM MENU - DEX. MAIN 
edit-db 

$THE OPEN DATABASE IS NEW 
FILE -.EXAMPLE DATABASE 
$*** NO TITLE *** 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
set-titl 



$PLEASE ENTER DATABASE TITLE 
$ENTER UP TO 64 CHARACTERS 
sample database< 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
create 
$ENTER TYPE 

$ENTER AN ITEM FROM MENU - DB-TYPES 
real 

$ENTER NAME 
length 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
create real diameter 



$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
create real height 
$ENTER A DATABASE COMMAND 
SENTER AN ITEM FROM MENU - DBEDCMDS 
create array-rl speedar 
$ERROR IN READING AN INTEGER VALUE 
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$BAD CHARACTER IS FLAGGED. PRIOR ITEMS ACCEPTED. 

$THE BAD VALUE AND SUBSEQUENT ITEMS MUST BE REENTERED 
$CREATE ARRAY-RL SPEEDAR 

$ $ENTER UP TO 1 INTEGER NUMBERS 

5 

$ENTER NAME 
speedar 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
create integer ncrew 
$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
create 
$ENTER TYPE 

$ENTER AN ITEM FROM MENU - DB-TYPES 
array-r 1 

$ENTER ARRAY SIZE 
$ENTER UP TO 1 INTEGER NUMBERS 
9 

$ENTER NAME 
power 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
Store 

$ENTER TYPE 

$ENTER AN ITEM FROM MENU - DB-TYPES 
real 

$ENTER NAME 
length 

$ENTER UP TO 1 REAL NUMBERS 

460. 

* 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
delete 
$ENTER NAME 
height 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
Store 

$ENTER TYPE 

$ENTER AN ITEM FROM MENU - DB-TYPES 
real 

$ENTER NAME 
ncrew 

$WRONG TYPE 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
Store integer ncrew 
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$ENTER UP TO 1 INTEGER NUMBERS 

100 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
Store 

$ENTER TYPE 

$ENTER AN ITEM FROM MENU - DB-TYPES 
ar ray-r 1 

$ENTER ARRAY SIZE 
$ENTER UP TO 1 INTEGER NUMBERS 
3 

$ENTER NAME 
speedar 

$ENTER UP TO 3 REAL NUMBERS 
5. 10. 

$ENTER UP TO 1 ADDITIONAL REAL NUMBERS 

20 . 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
Store array-rl 3 power 
$ENTER UP TO 3 REAL NUMBERS 
80000. 100000. 150000. 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
print diameter 
$DIAMETER 
$=UNDEFINED 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
print length 
$LENGTH 

$ 0.460000E+03 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
dump 

$TITLE: **SAMPLE DATABASE 



$ 



NAME 


TYPE 


VALUE COMMENT 


NCREW 


(I) 


100 


DIAMETER 


(R) 


**UNDEFINED** 


POWER 


(A) 


ARRAY ( 7 ) 


SPEEDAR 


(A) 


ARRAY ( 1) 


LENGTH 


(R) 


0.46000E+03 



THE ARRAYS 
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i 













1 ) 



$NAME; SPEEDAR , LENGTH= 3 ( 

$ 0.50000E+01 O.lOOOOE+02 0.20000E+02 

$NAME: POWER , LENGTH= 3 ( 7) 

$ 0.80000E+05 O.lOOOOE+06 0.15000E+06 

$ENTER A DATABASE COMMAND 
$ENTER AN ITEM FROM MENU - DBEDCMDS 
done 

$ ENTER AN ITEM FROM MENU - DEX.MAIN 

close-db 

$THE OPEN DATABASE IS 
FILE: EXAMPLE DATABASE 
$DO YOU WISH TO SAVE DATABASE? 

$ENTER AN ITEM FROM MENU ~ DXYES-NO 

no 

$ENTER AN ITEM FROM MENU ~ DEX.MAIN 

quit-dex 
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DEX ASSEMBLY LANGUAGE ROUTINES 
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